satis更轻量可控，适合纯内网；private packagist依赖外网激活，离线受限。需替换packagist.org源、禁用fallback、清缓存、确保packages.json可访问且格式正确。
私有 Packagist 服务必须用 Satis 还是 Private Packagist？
不用非得选，但 Satis 更轻量、更可控，适合纯内网场景；Private Packagist 是商业方案，依赖外网激活和定期 license 校验，离线环境基本不可用。
- Satis 是静态生成器，只输出
packages.json和一堆压缩包，部署到任意 HTTP 服务（Nginx/Apache/甚至 Python -m http.server）就能用 - Private Packagist 的 self-hosted 版本虽支持离线，但安装器本身要联网下载，首次 setup 后仍需定期连 vendor 服务器做 license heartbeat —— 内网断开后 30 天内会降级为只读
- 如果你已有 Git 仓库（如 Gitea/GitLab），Satis 可直接拉取 tag 和
composer.json，无需额外维护元数据
如何让 composer install 完全不碰公网？
关键不是屏蔽网络，而是彻底重写包发现路径 —— 必须覆盖默认的 packagist.org 源，并禁用所有 fallback 行为。
- 在项目根目录运行
composer config repo.packagist composer https://your-intranet/packagist/，这会把packagist.org替换为你的私有源地址 - 立刻执行
composer config --global repo.packagist false，否则全局配置仍可能触发回退到公网 - 检查
composer.json中不能出现"type": "package"或"dist"指向公网 URL 的条目，这类定义会在 install 时直连下载 - 加
--no-plugins参数启动，避免某些插件（如 composer-asset-plugin）偷偷加载外部资源
composer update 卡在 “Loading composer repositories” 怎么办？
这是最典型的离线失败信号，本质是 Composer 仍在尝试 HEAD 请求验证源可用性，哪怕你已配了私有地址。
- 确认私有源根路径下存在可访问的
packages.json，且响应头包含Content-Type: application/json，否则 Composer 会静默跳过该源 - 用
curl -I https://your-intranet/packagist/packages.json验证状态码必须是 200，302 重定向或 401 会导致超时后自动 fallback 到 packagist.org - 如果私有源走 HTTPS 且用了自签名证书，必须在 PHP 的
openssl.cafile中加入内网 CA 根证书，否则 cURL 层就失败，Composer 不报明确错误，只无限等待 - 临时调试可加
-v参数，看到类似Downloading https://repo.packagist.org/packages.json就说明配置没生效，不是网络问题，是源未正确注册
私有包版本更新后，composer update 为什么还是拉旧版？
因为 Composer 默认缓存 packages.json 一小时，且不会主动检测源文件变更 —— Satis 生成的索引不是实时 API，它是一次性快照。
- 每次 Satis 构建后，必须手动清空 Composer 全局缓存：
composer clear-cache，否则它继续读本地缓存的旧packages.json - 不要依赖
composer update --with-dependencies自动识别新 tag：Satis 默认只收录带composer.json的 tag，且要求 tag 名符合v1.2.3格式，1.2.3或release-1.2.3均无效 - 若私有包用
path类型本地开发，上线前务必改回vcs类型并指定"url": "https://your-git/internal-package"，否则composer install --no-dev在构建机上会因路径不存在而失败
内网环境下最麻烦的从来不是搭建，而是缓存链路上的每一环 —— PHP OPcache、Composer 自身 cache、HTTP 代理缓存、甚至浏览器对 packages.json 的 304 缓存，都可能让你反复看到“明明更新了却没生效”的现象。
