全局配置镜像源必须执行composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，缺-g、键名错、漏composer类型或URL末尾无斜杠均静默失效；验证需运行composer config -g repo.packagist，输出应为对应URL或JSON对象。
直接说结论：不配镜像源，composer install 卡在 Downloading 是默认行为，不是网络问题，是还在直连 packagist.org；企业项目必须用项目级 repositories + 显式禁用 packagist.org，否则私有包永远被跳过。
怎么全局配镜像源才真正生效？
全局配置是最省事、最稳的起点，但很多人执行了命令却没验证是否真走镜像。
- 执行
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，这条命令永久生效，所有新项目默认走阿里云镜像 - 验证方式必须是
composer config -g repo.packagist，输出应为该 URL 字符串（新版）或类似{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}（旧版） - 如果提示
Could not open input file: composer，说明composer没进系统PATH，查安装路径（如/usr/local/bin/composer），补环境变量 - 若报
Warning: putenv() has been disabled，去php.ini检查disable_functions，删掉putenv和proc_open，再重启 PHP-FPM 或 Apache - 别用已下线的
https://packagist.phpcomposer.com（2022 年停更），现在访问会 404 或跳转失败
项目级 repositories 怎么写才不被忽略？
私有仓库必须出现在 repositories 数组首位，且必须显式关闭官方源，否则 Composer 找到同名包就立刻停在 packagist，根本不会往后看你的私仓。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
repositories必须是 JSON 数组，不能是对象；每项至少含"type": "composer"和以/结尾的url（例如"https://satis.internal/"✅，"https://satis.internal/packages.json"❌） - 禁用官方源必须单独加一项：
{"packagist.org": false}，它不能塞进repositories里的某条仓库对象里，也不能放在config下 - 如果还想保留 packagist 作 fallback，得在
repositories数组末尾加{"packagist.org": true}，不能写成{"type": "composer", "url": "https://packagist.org"}，后者会冲突 - 常见错误：把
{"packagist.org": true}放第一位 → 所有包都走官方源，私仓彻底失效
为什么 Satis 构建后 composer install 还找不到包？
Satis 不是服务，只是静态构建器；它不报错、不扫描、不自动收录——包进不进索引，全看 satis.json 里有没有明确声明。
-
require-all: true看似方便，实则高危：只要其中一个仓库没打合法 tag 或缺失composer.json，整个构建就中断。建议改用显式require，例如"vendor/internal-lib": "dev-main" - vcs 类型仓库中，Composer 完全忽略包自身
composer.json里的version字段，只认 Git 的 tag：要让"^1.0"生效，必须打语义化 tag（v1.0.0或1.0.0），v1.0不识别 - ZIP 包必须可访问：确保 Nginx/Apache 允许
/dist/路径，且响应头含Content-Type: application/zip；用curl -I验证，否则 Composer 会静默 fallback 到 git clone - Web 服务器 root 必须和
php bin/satis build的输出路径完全一致，不能是子目录；别用php -S跑开发服务器，它缺关键响应头
认证凭据为什么总被静默忽略？
Composer 对认证极其严格：文件位置、权限、JSON 结构、域名大小写，任一出错都不报错，只安静跳过。
-
auth.json必须放在项目根目录（与composer.json同级）或COMPOSER_HOME目录下 - Linux/macOS 下权限必须是
600，否则 Composer 静默忽略；Windows 下无此限制但建议统一 - 内容结构必须是标准 JSON，
http-basic和github-oauth是平级字段；域名必须和仓库 URL 完全一致（satis.internal≠www.satis.internal） - HTTPS 私有源绝不能把 token 拼进 URL（如
https://token@），也绝不能写进composer.json；SSH 方式不依赖auth.json，但要求当前用户已将私钥加载进ssh-agent
最容易被忽略的是三件事：一是 {"packagist.org": false} 必须独立存在且位置靠前；二是 Satis 构建输出路径和 Web root 必须一字不差；三是 auth.json 权限错一次，整个认证链就断了，而 Composer 从不告诉你哪里错了。
