如何在Composer中配置使用自建的Satis私有包镜像？-composer-PHP中文网

因为repositories未置顶、未配"packagist.org": false或url缺末尾斜杠，且satis仅生成静态文件需web服务器正确托管packages.json，否则composer根本不会访问私有源。

如何在composer中配置使用自建的satis私有包镜像？

为什么直接写 `repositories` 还是拉不到私包？

绝大多数失败不是网络不通，而是 Composer 根本没去你部署的地址查包——它默认只连 packagist.org，除非你明确告诉它“别连官方源，改去这个地址”。repositories 字段必须放在项目根目录的 composer.json 顶层，且必须搭配 "packagist.org": false 才生效。

repositories 写在子对象里（比如嵌套在 require 下）会被忽略
url 必须以 / 结尾，否则 Composer 拼路径时会错成 https://pkg.example.com/packages.json（少一层斜杠），而实际需要的是 https://pkg.example.com//packages.json
私有源要放在 repositories 数组第一位，Composer 按顺序查找，不会合并同名包
全局配置 composer config -g repositories.xxx 在 CI/容器环境里通常不生效，优先用项目级配置

`satis build` 成功但 `composer install` 报 404 或 “could not find package” 怎么办？

这几乎 100% 是 Web 服务器没托管对静态文件，而不是 Satis 构建失败。Satis 只生成文件，不启动服务；你得用 Nginx/Apache 把输出目录设为 Web 根路径，并确保能直接访问 packages.json。

Composer

Composer 是 PHP 生态常用依赖管理工具，用于安装框架、组件和项目依赖。

下载

Nginx 的 root 必须和 satis.json 里的 output-dir 完全一致（推荐绝对路径，如 /var/www/satis）
访问 https://pkg.example.com/packages.json 必须返回 HTTP 200 + Content-Type: application/json；Nginx 要加 types { application/json json; }
如果部署在子路径（如 https://example.com/satis/），satis.json 中的 homepage 和客户端 url 都得匹配该路径，否则所有 dist.url 会拼错
检查 Web 服务器是否返回了 HTML（比如 Nginx 默认欢迎页），说明请求根本没落到 packages.json 上

`satis.json` 哪些字段写错会导致静默丢包？

Satis 构建过程不报错，但包没进索引，下游就永远看不到——这是最隐蔽的坑。常见静默丢包原因集中在 repositories、require 和 Git 凭据三处。

repositories 里用了 "type": "vcs"，但 URL 是字符串（如 "url": "https://git.internal/pkg"），没写成完整对象 → Satis 静默跳过
require-all: true 时，目标 Git 仓库没打任何符合语义化版本规范的 tag（如 v1.2.0 或 1.2.0），dev-main 不算 → 该包直接消失
HTTPS 私仓没配 git config --global credential.helper store，或没用 token；SSH 私仓没配好 ~/.ssh/config 或 key 权限 → clone 失败，Satis 不提示，直接跳过
目标仓库根目录下 composer.json 缺 name 字段，或含大写字母/下划线 → Satis 拒绝收录

如何让 `composer install --prefer-dist` 真正下载 ZIP 而不是 clone？

默认 Satis 不生成 ZIP 归档，composer install --prefer-dist 会 fallback 到 --prefer-source（即 git clone），这在离线或内网环境会失败。必须显式启用 archive 配置，并确保 Web 服务器允许访问 dist/ 路径。

在 satis.json 中加上："archive": {"directory": "dist", "format": "zip", "prefix-url": "https://pkg.example.com/dist/"}
prefix-url 必须可公开访问，且末尾带 /dist/（注意不是 /dist）
Nginx/Apache 必须允许访问 dist/ 子目录下的所有文件，不能限制后缀或加鉴权
如果要用 dev-main 版本，需在项目 composer.json 中加 "minimum-stability": "dev"，否则 Satis 即使生成了 ZIP，Composer 也不会选它

真正卡住人的从来不是命令怎么敲，而是 Satis 生成的文件在哪、谁来提供 HTTP 服务、Composer 到底连了哪个 URL——这三个环节只要一个没对齐，就会报错，而且错误信息完全不指向真实原因。