composer config -g repo.packagist 对 Satis 无效，因其仅修改元数据入口，不更新 packages.json 中 dist.url 字段；Satis 必须自行生成内网 ZIP 地址，否则 install 仍走外网。
为什么composer config -g repo.packagist对Satis无效
这条命令只改元数据入口，不碰 ZIP 包的下载地址。Satis 生成的 dist/ 下 ZIP 文件路径（如 https://pkgs.internal/dist/monolog/monolog/2.10.0/xxx.zip）必须由 Satis 自己写进 packages.json 的 dist.url 字段里，而 composer config -g 完全不修改这个字段。
验证是否生效：运行 composer show monolog/monolog --verbose，看输出里的 dist.url 是否指向你的内网地址。如果是 https://github.com/... 或 https://api.github.com/...，说明 ZIP 还在走原始源，镜像没真正接管。
- CI 环境或宝塔等面板默认读不到全局配置，更没法覆盖
dist.url - 多用户共享服务器时，
--global配置可能被不同用户覆盖或忽略 - 哪怕
packages.json能正常 GET 到，只要dist.url指向外网，composer install就会在局域网卡死
Nginx 配置必须显式声明 application/json MIME 类型
Composer 解析 packages.json 时会严格检查 Content-Type 响应头。如果 Nginx 返回的是 text/plain（默认行为），Composer 直接拒收，报错类似 Invalid response header: Content-Type: text/plain，而不是 404。
正确配置示例（Nginx）：
location / {
root /var/www/satis/web;
types { application/json json; }
add_header Content-Type application/json;
}
-
root必须精确指向satis.json中output-dir的子目录（通常是web/），比如"output-dir": "/var/www/satis"→ Nginxroot /var/www/satis/web; - 不要依赖
default_type或省略types块，json后缀必须显式绑定到application/json - 访问
https://pkgs.internal/packages.json后用curl -I检查响应头，确认Content-Type: application/json
项目级 composer.json 必须同时满足三项硬性条件
私有源声明不是可选优化，而是强制开关。漏掉任意一项，Composer 就不会查你的镜像，仍 fallback 到 packagist.org 或直接报错。
-
"repositories"数组必须放在项目根目录的composer.json里，不是 Satis 自己的配置文件，也不是包内部的composer.json -
"url"值必须以/结尾，例如"https://pkgs.internal/"；少一个斜杠，Composer 会拼成https://pkgs.internalpackages.json -
"packagist.org": false必须作为顶层字段，和"repositories"并列，不能嵌套在某个仓库对象内部，也不能写成"packagist": false
正确结构片段：
{
"repositories": [
{"type": "composer", "url": "https://pkgs.internal/"}
],
"packagist.org": false
}
satis.json 中 repositories 写错就白构建
Satis 不会自动扫描 Git 仓库所有分支或通配匹配，它只处理你明确列出的 repositories 数组中的每个仓库，并且每个元素必须是完整对象，不能是字符串 URL。
- 错误写法：
"repositories": ["https://git.internal/lib.git"]→ 构建静默跳过，packages.json为空 - 正确写法：
"repositories": [{"type": "vcs", "url": "https://git.internal/lib.git"}] -
"require-all": true和"require": {...}不能共存；混用会导致部分包被跳过，且无任何警告 - Git URL 必须带
.git后缀，且确保构建机和客户端都能git clone成功（HTTP 需开启 Git over HTTP，SSH 需配好公钥）
最容易被忽略的一点：Satis 不代理、不转发、不查 packagist.org。它只处理你写死在 repositories 里的那些仓库。想镜像外部包，得自己加一条 {"type": "composer", "url": "https://packagist.org"}，但企业场景下这反而引入不可控依赖和限流风险。
