私有仓库需构建、声明、认证三步全对齐：Satis 一次性生成 packages.json，输出路径须与 Web 服务器 root 完全一致；Nginx 需显式配置 JSON MIME 类型；composer.json 中私有源须置首位、type 为 "composer"、url 以 / 结尾，并设 "packagist.org": false；认证通过 auth.json 管理，权限与路径大小写必须严格匹配。
私有仓库不是加个 URL 就能用，关键在构建、声明、认证三步全对齐；否则 composer install 会静默跳过你的包，或报 Unable to load package list 却不提示具体哪一环断了。
php bin/satis build 为什么没生成 packages.json？
Satis 不是服务进程，它只是一次性静态构建工具。常见失效原因不是配置错，而是 Web 服务器根本没看到生成的文件。
-
php bin/satis build satis.json /var/www/satis的输出路径必须和 Nginx/Apache 的 root 完全一致，不能是子目录（比如/var/www/satis/web） - Nginx 必须显式支持 JSON MIME 类型：
add_header Content-Type application/json;要放在location ~ \.json$块里，不是 server 全局 - 别用
php -S跑开发服务器——它返回 200 状态码但缺失 Composer 所需的Content-Type和重定向逻辑，composer install会直接放弃请求 - 检查输出目录权限：Web 进程用户（如 www-data）必须有读取
packages.json和所有dist/ZIP 文件的权限
composer.json 里怎么声明私有仓库才不被忽略？
Composer 查源是顺序匹配，且默认 fallback 到 packagist.org；声明位置和关闭回退缺一不可。
- 把私有源放
repositories数组首位，type 必须是"composer"，url 必须以/结尾（https://satis.internal/packages.json/✅，https://satis.internal/packages.json❌） - 显式禁用公共源：
"packagist.org": false要作为独立项写进repositories，不是 config 下的字段 - 若仓库需要认证，不要硬编码密码；用
auth.json放{"http-basic": {"satis.internal": {"username": "xxx", "password": "yyy"}}，再设COMPOSER_AUTH环境变量注入 CI - 验证是否生效：运行
composer config --list，确认repo.my-private-repo出现在列表里，且值是你填的完整 URL
require-all: true 为什么总卡住构建？
require-all: true 会让 Satis 尝试解析所有 repositories 下每个包的 composer.json，只要其中一个缺失 dist 或分支信息，整个构建就中断。
- 改用显式
require：只列你真正要发布的包，例如"vendor/internal-lib": "dev-main" - 每个被 require 的包，其 Git 仓库必须有可访问的
dist归档（GitHub/GitLab 自动提供），或确保satis.json中启用了"archive": {"directory": "dist", "format": "zip", "skip-dev": false} - 若依赖 dev 分支，必须在包自己的
composer.json里设"minimum-stability": "dev"，且"branch-alias": {"dev-main": "1.0.x-dev"}存在，否则 Satis 无法推导版本号 - CI 构建时，建议加
--no-interaction --verbose参数，失败时能看到具体是哪个包的composer.json解析出错
为什么开发者执行 composer require 拉不到私有包？
问题常不在仓库本身，而在本地环境没走对源——尤其是当项目已有 composer.json 且含其他 repositories 时。
- 先运行
composer clear-cache，再composer show vendor/private-package，如果返回 “Package not found”，说明源根本没命中 - 检查项目级
composer.json是否覆盖了全局配置：执行composer config --list对比--global输出，确认repositories没被项目配置清空 - Windows 用户注意：若设了
COMPOSER_HOME，路径必须为绝对路径（如C:\Users\Me\.composer），不能含%USERPROFILE%或~，否则auth.json读取失败 - 最易忽略的一点：私有包的
name字段必须和require时写的完全一致（包括 vendor 名大小写），Composer 不做模糊匹配
真正的难点从来不在“怎么搭”，而在于构建产物能否被 Composer 的 HTTP 客户端干净地解析——这要求 MIME 类型、URL 路径、JSON 结构、认证头四者严丝合缝，漏一个，packages.json 就变成 404 或 200 空响应。
