Composer自定义仓库需同时满足三条件：仓库服务可访问、包元数据可解析、认证凭据已就位；漏任一环，install会卡在版本解析失败或401错误。
直接说结论：Composer 自定义仓库不是“加个 URL 就能用”，必须同时满足三件事：仓库服务可访问、包元数据可解析、认证凭据已就位。漏掉任意一环，composer install 都会卡在 Could not parse version constraint 或 401 Unauthorized 上。
怎么让 Composer 找到你的私有包
关键不在项目 composer.json 里写不写 repositories，而在于 Composer 能否从该仓库地址成功获取 packages.json（或等效的包索引）。Satis、Private Packagist、Toran Proxy 这类服务会生成这个文件；纯 Git 仓库则不会——它需要 Composer 自己去 clone 并解析 composer.json，仅限 "type": "vcs" 场景。
常见错误现象：
- 加了
"type": "composer", "url": "https://packages.example.com"，但访问该 URL 返回 404 或 HTML 页面 → 说明服务没跑起来，或路径不对（Satis 默认生成web/packages.json，URL 必须指向该文件所在目录） - 用了
"type": "vcs"，但composer install报Failed to download vendor/package: No source found for dev-main→ Git 仓库没打 tag，或分支名拼错（dev-main要求存在main分支）
实操建议：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 先手动
curl -I https://packages.example.com/packages.json，确认返回200 OK和Content-Type: application/json - 如果是 Satis，确保构建命令执行成功：
php bin/satis build satis.json web/，且web/目录被 Web 服务器（如 Nginx）正确映射为根目录 - VCS 类型不要滥用：仅当包极少、更新极慢时才用；高频迭代或大量包请上 Satis 等静态索引服务
auth.json 是怎么被读取和使用的
auth.json 不是“配置文件”，而是 Composer 的凭证缓存层。它只在两种场景生效：HTTP Basic 认证（http-basic）和 Bearer Token（bearer-token）。Git SSH 密钥、GitHub PAT、GitLab CI 变量都不走这个文件。
容易踩的坑：
- 把 GitHub 的 Personal Access Token 写进
http-basic→ 错。GitHub 不接受 Basic Auth，必须用bearer-token或 SSH - 全局配置了
http-basic.github.com，但项目里又用git@github.com:SSH URL → 凭证不生效，因为 SSH 完全绕过 HTTP 认证流程 - CI 环境中
auth.json未挂载或权限错误（Composer 要求600）→ 报file_get_contents(/root/.composer/auth.json): failed to open stream
实操建议：
- 本地调试时，用
composer config --global http-basic.example.com user pass，然后检查~/.composer/auth.json是否生成对应字段 - CI 中优先用环境变量注入凭据：
COMPOSER_AUTH='{"http-basic":{"example.com":{"username":"$USER","password":"$PASS"}}}' composer install - Git 仓库统一用 SSH 方式（
git@...），避免所有 HTTP 凭证管理问题
require-all 和 require 的实际行为差异
"require-all": true 不是“拉所有包”，而是“扫描所有仓库中所有 tagged 版本的包”。它会忽略没有打 Git tag 的提交，也不会处理 dev- 前缀的开发分支。而 "require" 是精确匹配：只收录明确列出的包名 + 版本约束，哪怕那个包根本不在任何 repositories 列表里，Satis 构建时也会报错。
性能与兼容性影响：
- 仓库含 50+ 包时，
require-all构建时间可能翻倍（每个包都要git ls-remote查 tag） -
require更安全：避免意外引入未审核的内部包；但要求每个包名必须和其composer.json里的"name"完全一致（包括大小写、斜杠方向） - Satis 构建后生成的
packages.json里，require-all会把所有包平铺，require则只列明文指定的
实操建议：
- 初期用
require-all快速验证流程；上线前切到require白名单模式 - 包名拼错是最常见的构建失败原因，运行
php bin/satis build satis.json web/ --no-interaction --verbose查看具体哪个包 resolve 失败 - 不要在
require里写"*"，它会导致 Satis 尝试解析所有分支，极易超时；用"^1.0"或"dev-main"明确限定
全局配置 vs 项目级配置的优先级陷阱
composer config --global repositories.xxx 确实能让所有项目“看到”私有仓库，但一旦项目 composer.json 里也写了 repositories，全局配置就完全失效——Composer 采用“覆盖而非合并”策略。
这导致两个典型问题：
- 团队成员本地加了全局仓库，CI 流水线却因缺少项目级声明而失败
- 某项目临时禁用某个仓库（比如注释掉
repositories），结果发现其他依赖仍从全局仓库安装，行为不一致
实操建议：
- 禁止在生产项目中依赖全局仓库；所有
repositories必须显式写在项目composer.json的repositories字段里 - 全局配置只用于开发者镜像加速（如阿里云源）或临时调试，CI 脚本里一律用
-d COMPOSER_HOME=/tmp/composer隔离环境 - 用
composer config --list --global和composer config --list对比，确认当前上下文实际生效的是哪一套配置
最常被忽略的一点：Satis 生成的 packages.json 是静态快照，不支持实时查询。如果你改了某个包的 composer.json 但没重新 build，Composer 依然会按旧元数据安装——它根本不知道你改了什么。
