composer怎么配置自建的Satis仓库_composer静态镜像搭建【指南】

常见原因是Satis生成的packages.json未被识别或composer未禁用packagist.org默认源；需确保repositories在composer.json顶层、packagist.org设为false、URL以/结尾、正确配置认证及权限，并清除Composer缓存。

为什么 composer.json 里加了 repositories 还是拉不到私包？

常见原因是 Satis 生成的 packages.json 没被正确识别，或者 Composer 没跳过 Packagist 默认源。Satis 本身不提供实时服务，只是静态文件集合，必须显式禁用默认源，否则 Composer 仍会优先查 packagist.org。

实操要点：

• 在项目根目录的 composer.json 中，repositories 必须放在顶层，且 packagist.org 要设为 false
• 确保 Satis 生成的仓库地址以 / 结尾（如 https://pkg.example.com/），否则 Composer 会拼错 packages.json 路径
• 如果用了 HTTP Basic Auth，要在 URL 里带上凭证：https://user:pass@pkg.example.com/，或配 auth.json

典型配置示例：

{     "repositories": [         {             "type": "composer",             "url": "https://pkg.example.com/"         }     ],     "packagist.org": false,     "require": {         "myorg/private-package": "^1.2"     } }

运行 satis build 时提示 “Could not fetch packages” 或 “No valid packages found”

本质是 Satis 扫描不到你定义的包源 —— 它不自动读取 git 仓库或本地路径，必须手动列出所有包的 name 和 version，或通过 providers 指向一个可用的 Composer repo（比如另一个 Satis 实例、github 的 composer.json、甚至 packagist.org）。

常见原因与对策：

• satis.json 里只写了 output-dir 和 repositories，但没写 require-all 或具体 require 列表 → 补上 "require-all": true，或明确列出包名："require": {"myorg/private-package": "*"}
• 目标包的 composer.json 缺少 name 字段，或 name 格式非法（如含大写字母、下划线）→ Satis 会直接跳过，检查并修正
• 使用 type: vcs 指向私有 Git 仓库时，未配置 ssh key 或 HTTPS 认证 → 改用 type: package 手动声明，更可控

如何让 Satis 镜像支持 dev-master 或带分支别名的版本？

Satis 默认只导出稳定版本（stable），dev- 开头的开发分支不会自动收录，除非你在 satis.json 中显式开启 archive 或设置 require-dependencies，但这不是根本解法。真正起作用的是 minimum-stability 和 prefer-stable 的组合行为。

关键操作：

• 在 satis.json 中添加："minimum-stability": "dev"，并确保对应包的 composer.json 里有 "minimum-stability": "dev" 或显式声明分支别名（如 "dev-main as 2.0.x-dev"）
• 运行 satis build 时加 --skip-errors，避免单个包失败中断整个构建
• 若需压缩归档（.zip），启用 "archive": {"Directory": "dist", "format": "zip", "skip-dev": false}，其中 skip-dev: false 才会打包开发分支

为什么 composer install 卡在 “Loading from cache” 或返回 404？

这不是网络问题，而是 Composer 缓存了旧的 packages.json 元数据，或 Satis 生成的 JSON 文件权限/路径不对。Satis 输出的是纯静态文件，没有服务器端逻辑，所以任何路径错误、MIME 类型缺失、或 nginx/apache 未正确配置 index.html 回退，都会导致 404。

排查顺序：

• 直接浏览器访问 https://pkg.example.com/packages.json，看能否下载到 JSON 内容；如果 404，检查 Web 服务器是否把该路径映射到了 Satis output-dir 目录
• 执行 composer clear-cache，再试 composer update --no-cache 强制重拉元数据
• 确认 Satis 生成的 packages.json 文件权限为 644，且所在目录可被 Web 用户读取（常见于 docker 挂载或 SElinux 环境）
• 如果用了 CDN 或反向代理，确保它没缓存 packages.json 的 304 响应 → 加 Cache-Control: no-cache 头

最易忽略的一点：Satis 不生成 provider-* 分片文件，除非你启用了 "providers": true 并配合大量包使用；小规模私仓反而要关掉它，否则 Composer 会去请求不存在的分片路径。