常见原因是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 服务器是否把该路径映射到了 Satisoutput-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 会去请求不存在的分片路径。
