根本原因在于satis.json未正确配置require或require-all，导致包未被索引入packages.json；Satis仅处理显式声明的包和版本，不自动扫描仓库，且需配合Nginx/Apache正确托管、URL以/结尾、项目级composer.json声明私有源并禁用packagist.org。
satis.json 里 require-all 或 require 写不对，包就根本不会进索引
绝大多数“composer install 找不到私有包”的问题，根源不是网络或权限，而是 satis.json 没真正把包纳入索引。Satis 不会扫描 Git 仓库所有分支或 tag —— 它只认你明确写进 require 或 require-all 的内容。
-
"require-all": true：拉取repositories列表中每个 VCS 仓库的所有合法 tag（如v1.0.0、2.3.1）和 stable 分支（如main、master），但默认跳过dev-前缀分支；如需包含，得加"skip-dev": false -
"require": { "vendor/package": "*" }：只匹配该包的语义化版本 tag（如v1.2.0）；若仓库没打任何 tag，这个包就静默消失 - 如果用了
"type": "vcs"但没在require或require-all中声明，Satis 构建时完全跳过，不报错也不生成元数据 - Git 仓库根目录下必须有合法
composer.json，且name字段必须全小写 + 短横线（如acme/utils），含非法字符或大小写混用会导致解析失败、包被丢弃
Web 服务器没配对，packages.json 就是 404 或 MIME 错误
Satis 只生成静态文件，不提供 HTTP 服务。Nginx/Apache 配置错一个细节，composer install 就会卡在 “Could not fetch” 或 “Invalid response body”。
-
root必须精确指向satis.json中的output-dir值（如/var/www/satis/web），不能多一层或少一层 - Nginx 必须显式声明 JSON MIME 类型：
types { application/json json; }，否则返回text/plain，Composer 直接拒绝解析 - URL 必须以
/结尾（如"url": "https://pkg.internal/"），否则 Composer 拼路径时变成packages.json/导致 404 - 访问
curl -I https://pkg.internal/packages.json应返回HTTP/2 200+Content-Type: application/json；缺一不可
dist ZIP 下载失败，其实是 Web 服务器没放行 dist 路径或 MIME 不对
想让 composer install --prefer-dist 真正走 ZIP 下载而非回退到 git clone，光在 satis.json 开 archive 还不够。
-
archive配置必须启用："archive": { "format": "zip", "skip-dev": true, "directory": "dist" } - 生成的 ZIP 路径形如
dist/vendor-package/1.0.0-hash.zip，Nginx/Apache 必须允许该路径被公开访问（无 rewrite 截断、无 403） -
curl -I https://pkg.internal/dist/vendor-package/1.0.0-hash.zip必须返回Content-Type: application/zip；否则 Composer 或浏览器可能拒绝下载 - 若仍 fallback 到 source，运行
composer install -v看具体提示——常见原因是 ZIP 404，或packages.json里dist.url字段拼错了（比如少了个/）
客户端 composer.json 配置顺序和 packagist.org 开关没设对，私有源就无效
即使 Satis 服务完全正常，项目里不改配置，Composer 还是优先去 Packagist 找包，结果报 Could not find package。
立即学习“PHP免费学习笔记（深入）”；
- 必须在项目顶层
composer.json的repositories数组里声明私有源，type必须是"composer"，不是"vcs"或"package" - 私有源 URL 必须可被
curl直接访问到packages.json，且返回状态码 200、Content-Type正确 - 必须显式禁用 Packagist 回退：
"packagist.org": false放在repositories同级的config块里，否则 Composer 仍会尝试查官方源 - 全局配置（
composer config -g）虽方便，但易被 CI 环境覆盖或与项目级冲突；推荐优先用项目级配置，更可控、可审计
php bin/satis build；不接入 CI 在 push tag 后触发构建，下游永远看不到新版。 
