离线环境让 composer 找到私有包的核心是使用 artifact 仓库类型：将所有包按 vendor-name/package-name-version.tar.gz 命名打包，配置 composer config repositories.offline '{"type":"artifact","url":"/path/to/artifacts/"}'，并确保 composer.lock 中 dist.url 改为 file:/// 协议指向本地压缩包。
离线环境怎么让 composer 找到私有包？
核心是绕过网络请求，把包源“固化”进本地。不能依赖 packagist.org 或远程 VCS（如 GitHub），得提前把包的元数据和代码都落盘，再用 composer config 指向本地路径。
常见错误现象：composer install 卡在 Updating dependencies，或报错 Could not fetch https://repo.packagist.org/packages.json —— 这说明它还在试图联网。
- 必须提前在有网机器上完整执行一次
composer update --no-install，生成带完整依赖树的composer.lock - 把所有依赖包的源码（含
composer.json）打包成tgz或放本地目录，结构要符合 Composer 的仓库协议（如packages.json索引文件 + 包目录） - 离线机上运行
composer config repositories.my-private '{"type":"package","package":{...}}'不可靠，仅适用于单个包；多包必须用artifact或path类型仓库
artifact 仓库为什么最适合离线场景？
因为它是 Composer 原生支持的离线模式：把所有包压缩包（.tar.gz）放一个目录，Composer 只读取这些文件，不发任何 HTTP 请求。
使用场景：企业内网、CI 构建机、客户现场部署等完全断网环境。
- 压缩包命名必须严格为
vendor-name/package-name-version.tar.gz，例如acme/utils-1.2.0.tar.gz - 每个压缩包里必须包含完整的
composer.json，且name和version要与文件名一致 - 配置方式：
composer config repositories.offline '{"type":"artifact","url":"/path/to/artifacts/"}' - 性能影响：首次
install会解压所有匹配包，但比远程下载稳定；不支持按需拉取，所以artifacts/目录要预装全量依赖
path 仓库在开发联调时怎么避免误提交？
适合本地调试多个私有包，但容易因路径硬编码导致上线失败。
常见错误现象：composer install 在 CI 上报错 Could not find package acme/utils at version dev-main —— 因为 path 仓库只在本机有效，且默认启用 symlink，一旦删掉源目录，项目就崩。
- 必须加
"options": {"symlink": false}，强制复制而非软链，否则离线机上路径失效 - 配置中路径要用相对路径（如
../my-utils），别用绝对路径（/home/user/my-utils），否则换机器就挂 - 上线前务必删掉
repositories配置块，或用composer config --unset repositories.my-local清理，否则可能覆盖正式仓库源 - 兼容性注意：
path类型不支持dist模式，所有安装都是source，体积大、速度慢，仅限临时开发
离线 composer.lock 文件最容易被忽略的三个点
很多人以为只要拷贝 vendor 目录就行，其实 composer.lock 才是关键凭证 —— 它锁定了每个包的 dist.url 和 dist.shasum，而离线时这些 URL 必须指向本地路径。
-
dist.url字段在离线环境中必须全部替换为file:///协议的本地路径，比如"dist": {"url": "file:///opt/artifacts/acme-utils-1.2.0.tar.gz", ...} - 如果用了
artifact仓库，composer.lock中的type会自动变成artifact，但dist.url仍可能是原始远程地址，必须手动修正 - 每次在有网机上
update后，都要重新生成一遍离线版lock文件，并校验所有dist.shasum是否与本地压缩包一致，否则安装会校验失败
