根本原因在于composer需http服务响应packages.json查询并提供dist归档，直接克隆或复制无效；唯一可行方案是satis，其构建静态镜像须满足三硬性配置：require-all:true、完整archive块、repositories为对象数组，且项目级必须显式禁用packagist.org。
不能用 git clone 或 rsync 直接“克隆”Packagist 上的开源包到本地当私有仓库用——Composer 不认一堆零散的 ZIP 或 Git 仓库目录，它需要一个能响应 packages.json 查询、支持语义化版本发现、并提供可下载 dist 归档的 HTTP 服务。真正可行的方案只有 Satis。
为什么直接复制包文件或 git clone 私有仓库行不通
很多人把 GitHub 上 fork 的包 git clone 到内网服务器，再配 "type": "vcs"，结果 composer install 仍走外网或报错。原因很实在：
-
"type": "vcs"配置只在当前项目生效，其他项目必须重复写；CI 构建机没 SSH key 或 Token 就彻底失败 - Git 协议在 Docker 容器、无交互环境、企业防火墙下常被拦截，HTTPS + Token 又得每台机器配
auth.json - 没有
packages.json元数据，Composer 无法做版本约束解析，require "monolog/monolog": "^2.0"会直接 fallback 到官方源 - 不生成 ZIP 归档（dist），每次安装都触发
git clone，而内网通常禁用 Git 协议或限速
Satis 构建静态镜像的三个硬性配置点
Satis 是唯一轻量、稳定、无需数据库或后台进程的方案。它把元数据和 ZIP 打包成纯静态文件，扔进 Nginx 就能被所有机器访问。但以下三处漏掉任意一个，composer install 就拉不到包：
-
"require-all": true—— 否则只同步你当前项目require的包，其他 tag、dev 分支、历史版本全丢 -
"archive"块必须完整：{"directory": "dist", "format": "zip", "skip-dev": true}—— 缺这个，CI 构建时只能走git clone，不是下载 ZIP -
"repositories"必须是对象数组，每个源单独声明：{"type": "vcs", "url": "https://gitlab.internal/sdk"}—— 写成字符串 URL 或漏type，Satis 构建时直接跳过该仓库
全局镜像配置必须严格匹配格式
运行 composer config -g repo.packagist 输出必须是：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
{"type":"composer","url":"https://packagist.internal/"}
常见失效点：
- 键名写成
repos.packagist（多了一个s），Composer 静默忽略 -
url缺末尾斜杠，请求变成https://packagist.internal/packages.json→ 404 → fallback 官方源 - 没写
type字段，新版 Composer 默认 fallback，且不报错 - PHP 禁用了
proc_open或putenv，导致配置根本没写入（检查php.ini并重启服务）
项目级 repositories 必须显式声明同名源
即使已设全局镜像，项目 composer.json 中仍需加：
{
"repositories": [
{"type": "composer", "url": "https://packagist.internal/"}
],
"packagist.org": false
}
否则 Composer 仍会 fallback 到官方源查包。特别注意：
-
"packagist.org": false必须显式写，不能靠全局配置覆盖 - 如果项目已有其他私有源（如 GitLab vcs），
repositories必须是数组，不能写成对象嵌套 - CI 环境中
~/.composer路径可能不存在或权限不对，项目级配置才是唯一可靠方式
最易被忽略的是：Satis 生成的 packages.json 必须放在 Web 根目录下（如 /var/www/satis），且路径本身要能被直接 GET 到——比如 https://packagist.internal/ 指向的就是这个目录，而不是 https://packagist.internal/packages.json。一旦路径拼错，Composer 请求 404 后就静默走外网，连错误提示都没有。
