直接改composer config -g repo.packagist不等于私有镜像，因其仅接管packages.json元数据请求，ZIP包仍从原始dist.url（如GitHub）下载，而这些地址不受控、内网不可达、需OAuth头、易被限流，且国内镜像不托管ZIP；验证需composer show --verbose查dist.url是否仍指向外部源。
为什么直接改 composer config -g repo.packagist 不等于有了私有镜像
它只接管元数据（packages.json）请求，ZIP 包仍从原始 dist.url 下载——比如 https://github.com/monolog/monolog/releases/download/2.10.0/monolog-2.10.0.zip。而这些地址：
- 不受你控制，内网根本打不开 GitHub
- 需要
X-OAuth-Scopes头才能访问，否则返回403 - 被 CDN 或 rate limit 拦截后无 fallback
- 国内公开镜像（阿里云、USTC）根本不托管 ZIP，只做元数据 redirect
验证方式：运行 composer show monolog/monolog --verbose，看输出里 dist.url 字段是否还在指向 GitHub/GitLab。
satis.json 里三个字段漏一就失效
Satis 不校验配置语法，但缺关键字段会导致 packages.json 为空或客户端拒绝加载：
-
"name"和"homepage"必须同时存在，且homepage是完整 HTTPS URL，末尾带/（如"https://pkgs.internal/"） -
"archive"块必须显式声明：{"directory": "dist", "format": "zip", "skip-dev": true}；否则 CI 构建时拉不到 ZIP 包 -
"repositories"数组里每个项必须是"type": "vcs"（Git 地址），不能写成"type": "package"或混在require里
常见错误：satis build 成功但 packages.json 里没包——大概率是某个 Git 仓库没打语义化 tag（v1.0.0），或 composer.json 里缺 dist 字段。
Nginx 托管 packages.json 的三个硬性响应要求
Satis 输出的 public/ 目录扔到 Nginx 就完事？错。Composer 对 HTTP 响应极其挑剔：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- URL 必须以
/结尾（https://pkgs.internal/），否则拼出https://pkgs.internalpackages.json→404 -
packages.json响应头必须含Content-Type: application/json；Nginx 需显式配置：types { application/json json; }，不能依赖自动推断 -
dist/下的 ZIP 文件必须可直连 GET（如https://pkgs.internal/dist/monolog/monolog/2.10.0/abc123.zip），SELinux 或文件权限常锁死该路径
调试命令：curl -I https://pkgs.internal/packages.json，检查状态码和 Content-Type。
项目级 composer.json 怎么写才真正生效
私有源必须写在你要装包的那个项目的根级 composer.json 里，不是 Satis 自己的配置文件，也不是包自己的 composer.json：
- 类型必须是
"type": "composer"，URL 是托管packages.json的根地址（含末尾/） - 务必加上
"packagist.org": false，且放在repositories数组外层根节点，不是嵌套在某个仓库对象内部 - 私有源必须放在
repositories数组第一位，Composer 按顺序查找，不会合并同名
换源后必须手动删掉 vendor/ 和 composer.lock，再跑 composer install；update 没用，它照着旧 lock 文件里的 dist.url 下载。
最易被忽略的是：Satis 不是服务，只是静态构建器；所有问题最终都落在 Web 服务暴露是否合规、ZIP 路径是否真实可 GET、以及项目配置是否禁用了 packagist.org fallback —— 这三处任一缺失，都会让安装悄悄退回到公网。
