离线环境私有git包必须使用dist方式而非source，即通过预打包的zip/tar.gz文件配合显式dist配置实现安装。
私有 Git 仓库包在离线环境必须走 dist 而不是 source
Composer 默认拉取私有 Git 包时会走 source（即 clone 仓库），这在离线环境完全不可行。真正能用的只有 dist 方式——也就是提前下载好打包好的 .zip 或 .tar.gz 归档，再让 Composer 从本地路径或 HTTP 服务读取。离线环境下，dist 是唯一可行路径。
实操建议：
- 私有仓库必须配置
"dist": { "url": "...", "type": "zip" }，且url指向可离线访问的位置（如内网 HTTP 服务器、挂载的本地目录） - 打包时用
git archive --format=zip --output=vendor-v1.2.0.zip v1.2.0，确保归档根目录干净（不带仓库名前缀，否则 autoload 会失效） - 别依赖 GitHub/GitLab 的自动 dist 链接——它们需要在线调用 API 生成，离线时
composer install会卡在Failed to download vendor/package: No releases available
composer.json 里怎么写私有包的离线源？
不能只写 "repo.example.com/vendor/package": "dev-main" 这种裸引用，必须显式声明 dist 并禁用 source。否则 Composer 在离线时仍会尝试走 git clone 流程，报错 Cloning failed using an ssh command 或直接超时。
实操建议：
- 在项目根目录的
composer.json中，为私有包加完整定义：
{
"repositories": [
{
"type": "package",
"package": {
"name": "vendor/package",
"version": "1.2.0",
"dist": {
"url": "http://intranet/dist/vendor-package-1.2.0.zip",
"type": "zip"
},
"autoload": { "psr-4": { "Vendor\Package\": "src/" } }
}
}
],
"require": {
"vendor/package": "1.2.0"
}
}
- 如果用本地文件（比如 U 盘拷贝），
url写成file:///mnt/usb/dist/vendor-package-1.2.0.zip，注意三个斜杠和绝对路径 - 务必删掉
"source"字段，哪怕它为空——Composer 会优先 fallback 到 source，导致离线失败
离线安装时 composer install 报 Could not parse version constraint
这不是网络问题，而是 version 字段写法不合规。私有包走 package 类型仓库时，version 必须是明确的稳定版本字符串（如 "1.2.0"），不能写 "dev-main" 或 "*"，否则解析失败。
实操建议：
- 所有私有包的
version值必须和 dist 归档里的实际 tag/commit 语义一致，且符合 Composer 版本约束语法 - 如果想支持多版本，得为每个版本单独定义一个
package对象，或者改用composer repo搭建离线 Satis / Private Packagist 实例（但那是另一套运维成本） - 检查
composer show vendor/package是否能输出版本信息——离线环境下这条命令仍可运行，是快速验证定义是否生效的手段
HTTP dist 服务没配好，composer install 卡住不动
现象是命令长时间无响应，最后报 cURL error 28: Operation timed out。根本原因不是 Composer 本身，而是它发起的 HTTP HEAD 请求被拦截、重定向或返回了非 200 状态码（比如 403、302、503），而 Composer 默认不打印详细请求日志。
实操建议：
- 手动 curl 测试 dist URL：
curl -I http://intranet/dist/vendor-package-1.2.0.zip，确认返回HTTP/1.1 200 OK和正确的Content-Length - 确保 Web 服务允许 HEAD 方法（Nginx 默认关掉，需加
location块显式允许） - 避免使用需要登录态的 HTTP 服务（如带 Basic Auth 的 Nginx）——Composer 不会自动传凭据，除非你配了
auth.json，但那又引入新依赖点
离线环境最稳的方式，其实是把 dist 文件全拷进 vendor/composer/dist/ 目录并用 file:// 引用；但要注意 Composer 会校验 SHA256，所以打包后得用 composer install --no-plugins --no-scripts 绕过钩子，再手动补上 hash 值——这点很容易被忽略。
