绝大多数团队该直接用 satis，因其不依赖运行时服务、不连外网、部署后零维护；private packagist self-hosted 版需定期联网校验 license，内网断开即降级只读，实际不可靠。
私有 Packagist 该用 Satis 还是 Private Packagist？
绝大多数团队该直接用 satis，不是因为便宜，而是它不依赖运行时服务、不连外网、部署后零维护。Private Packagist 的 self-hosted 版本虽标称“离线可用”，但首次安装要联网下载镜像，后续每 30 天需向 vendor 服务器发心跳校验 license —— 内网断开就自动降级为只读，实际不可靠。
常见错误现象：composer install 突然拉不到新版本、satis build 卡在 Cloning into bare repository、或者生成的 packages.json 里压根没你的包。这些都不是配置问题，而是你误把 Satis 当成“带 Web 界面的 Packagist”在用。
- Satis 是静态生成器：只输出
packages.json+ ZIP 包，丢到 Nginx/Apache/甚至php -S就能当源用 - 它不处理权限、不跑 PHP-FPM、不存数据库，也**不支持实时同步**——每次更新必须手动
php bin/satis build - 如果你已有 GitLab/Gitea，
satis.json里写"type": "vcs"直接拉 tag，不用额外维护元数据
composer.json 怎么声明私有源才真正生效？
只往 repositories 数组里加一条 URL 是不够的。Composer 默认仍会 fallback 到 packagist.org，一旦同名包存在，就永远拉不到你的私有版。
必须同时满足三个条件：
- 私有源必须放在
repositories数组**首位**，且"type": "composer"（不能是package或vcs） -
url值**必须以/结尾**，否则 Composer 会拼错路径，去请求https://pkgs.example.com/packages.json变成https://pkgs.example.compackages.json（404） - 显式禁用默认源：
"packagist.org": false要写在repositories同级，不是嵌套在某个源里
正确示例：
{
"repositories": [
{
"type": "composer",
"url": "https://pkgs.internal.company/"
}
],
"packagist.org": false
}
auth.json 放错位置，认证就永远失败
composer install 提示 Authentication required 却死活过不去？大概率是 auth.json 放错了地方。Composer 查找凭据有严格顺序：
- 当前项目目录下的
auth.json -
$COMPOSER_HOME/auth.json（通常是~/.composer/auth.json） - 旧版路径
$HOME/.composer/auth.json（已弃用，但部分环境仍会读）
最稳妥做法是统一用全局配置：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
composer config -g http-basic.pkgs.internal.company username password
如果私有源走 token 认证（如 GitHub Packages），则用：
composer config -g http-basic.pkgs.internal.company your-token ""
注意密码字段留空 —— GitHub/GitLab/Artifactory 都只认用户名位置传 token。
为什么 composer update 卡在 “Loading composer repositories”？
这不是网络超时，而是 Composer 在尝试验证源可用性时失败了，且没报明确错误。本质原因只有两个：
- 私有源根路径下没有可访问的
packages.json，或响应头缺失Content-Type: application/json - 私有源用 HTTPS + 自签名证书，但 PHP 的
openssl.cafile没包含内网 CA 根证书，cURL 层静默失败
调试方法：
先用 curl -I https://pkgs.internal.company/packages.json 看状态码是否为 200；再加 -v 参数跑 composer update，如果看到 Downloading https://repo.packagist.org/packages.json，说明配置根本没生效，不是证书或网络问题。
容易被忽略的一点：satis build 生成的 packages.json 必须由 HTTP 服务直接返回，不能经由 PHP 脚本动态输出 —— 否则响应头无法控制，Composer 会跳过该源。
