Satis是静态包仓库生成器而非镜像源；需先推代码至Git仓库，再通过php bin/satis build生成packages.json和ZIP文件供composer require使用。
直接说结论：Satis 不是镜像源，而是静态包仓库生成器；你无法用 composer install 直接“发布”包到 Satis，必须先推代码到 Git 仓库（如 GitLab），再让 Satis 扫描并生成 packages.json 和 ZIP 归档。
为什么 composer publish 不存在？
Composer 本身没有发布命令 —— 它只是依赖安装工具。所谓“发布到私有源”，本质是两步：
- 你的包代码托管在私有 Git 服务器（
git@gitlab.example.com:team/my-package.git） - Satis 配置中声明该仓库地址，并定期运行
php bin/satis build生成可被composer require访问的静态 JSON + ZIP 文件
常见错误：试图用 composer config repositories 添加 Satis 地址后，再执行 composer push —— 这会报错，因为 Composer 不支持推送。
satis.json 必须包含哪些关键字段？
这是 Satis 的配置核心，漏掉任意一项都可能导致包不出现或安装失败：
-
name：仅用于生成页面标题，不影响功能 -
homepage：必须是能被客户端访问的 HTTP 地址（如https://satis.example.com），否则composer config repositories里填的 URL 就无效 -
repositories：列出所有 Git 仓库（支持git、package、vcs类型），Satis 会从中提取composer.json并构建元数据 -
require-all：设为true表示拉取所有分支/Tag；若只想要稳定版，改用require指定版本约束（如"my/package": "dev-main"） -
output-dir：生成文件的根目录（如web/），需确保 Web 服务器能直接访问其中的packages.json
{
"name": "My Private Packagist",
"homepage": "https://satis.example.com",
"repositories": [
{ "type": "vcs", "url": "git@gitlab.example.com:team/my-package.git" }
],
"require-all": true,
"output-dir": "web/"
}
如何让私有包支持 composer require my/package？
客户端机器上必须完成三件事，缺一不可：
- 在项目
composer.json中添加私有源："repositories": [{"type": "composer", "url": "https://satis.example.com"}] - 确保该 URL 可公开访问（或走内网 DNS），且返回的是合法 JSON（用浏览器打开
https://satis.example.com/packages.json应看到结构化数据） - Git 仓库的
composer.json里必须有name字段（格式为vendor/name），且与require中的名称完全一致（区分大小写） - 如果使用 SSH Git 地址（如
git@gitlab...），客户端执行composer install时需已配置好对应 SSH key，否则会卡在 “Cloning failed”
典型错误现象：Could not find package my/package at any version —— 多半是 Satis 没扫到 Git 仓库，或 packages.json 没更新，或客户端没加 repositories 配置。
权限和缓存最容易被忽略的点
Satis 生成的 ZIP 包默认无权限控制，任何人都能下载源码；而 Composer 客户端又会本地缓存 packages.json，导致改了 Satis 配置却看不到新包：
- Web 服务器（Nginx/Apache）要给
output-dir下的dist/目录开启Content-Disposition: attachment头，否则某些环境解压失败 - 每次修改
satis.json后，必须手动清空output-dir再重新运行php bin/satis build satis.json web/，否则旧包残留 - 客户端执行
composer clear-cache，否则可能还在用本地缓存的旧packages.json - 如果 Git 仓库用了私有 Token 或子模块，Satis 构建时需提前配置好
auth.json（放在 Satis 项目根目录），内容类似：{"http-basic": {"gitlab.example.com": {"username": "token", "password": "glpat-xxx"}}}
真正卡住人的，往往不是配置语法，而是 Git 权限没通、Web 路径没映射对、或者忘了清缓存 —— 这些细节比写 satis.json 更耗时间。
