离线使用Composer必须提前导出完整依赖快照（含composer.lock、元数据及dist包），否则install必卡在“Resolving packages…”；需禁用网络路径、配置本地仓库，并确保环境与lock文件生成环境严格一致。
离线环境用 Composer 不是“装个二进制就行”，核心矛盾是依赖解析和包下载两个阶段全部断网——必须提前把所有 composer.json 里声明的包、连同它们的元数据（packages.json、provider-*.json）一并带进来，否则 composer install 必然卡死在 “Resolving packages…”。
离线前必须导出完整依赖快照
在线机器上不能只跑 composer install 然后打包 vendor/。那只是运行时产物，没解决“下次在新机器上怎么重装”的问题。
- 先确保项目已执行过
composer update，生成最新composer.lock - 用
composer archive --format=zip --dir=./dist打包整个项目（含composer.json和composer.lock），不是只打vendor/ - 关键一步：运行
composer show --all --format=json > packages.json，它会输出所有已解析包的 name/version/dist-url，这是离线构建元数据的基础 - 若用私有包，还需手动收集对应 Git 仓库的
composer.json文件（确保含name字段且与require中完全一致）
离线服务器上禁用网络并配置本地仓库
直接运行 composer install 会默认尝试连接 packagist.org，必须显式切断网络路径并指明包来源。
- 全局禁用 HTTPS 检查（避免证书错误中断）：
composer config -g secure-http false - 清空远程仓库配置：
composer config -g repo.packagist "" - 添加本地 path 仓库（假设包解压在
/opt/composer-packages/）：composer config -g repositories.offline type path，再执行composer config -g repositories.offline url "/opt/composer-packages/{packageName}" - 注意：
{packageName}是占位符，实际目录名必须与composer.json中的name完全一致（如monolog/monolog→ 目录名必须是monolog/monolog，不能是monolog或Monolog）
composer install 卡在 “Loading composer repositories…” 怎么办
这不是网络超时，而是 Composer 在尝试读取远程 packages.json 元数据——离线时这个动作必须被绕过或替换。
- 确认是否误用了
--no-cache：离线环境反而要强制用缓存，删掉该参数 - 检查
composer.lock中的content-hash是否与当前composer.json匹配，不匹配会导致重新解析；可用composer validate校验 - 若仍失败，临时加
--ignore-platform-reqs排除 PHP 版本/扩展检查干扰（仅调试用，生产应提前校验） - 最稳妥方式：改用
composer install --no-plugins --no-scripts先完成基础安装，再单独处理插件和脚本逻辑
PATH 仓库 symlink 失效的典型表现和修复
本地开发常用 symlink 方式链接框架或组件，但离线部署时容易因权限或路径解析失败导致 could not find package。
- 确保 symlink 目标目录下存在合法
composer.json，且含"name"和"version"（或"minimum-stability": "dev"） - 在项目根目录的
composer.json中，repositories必须声明为type: "path"，不能是"package"或"vcs" - Linux 下注意挂载点权限：如果
/opt/composer-packages/在 NFS 或 bind mount 上，需确认composer进程用户对该路径有read+execute权限 - Windows 环境下避免路径含中文或空格，symlink 建议用
mklink /D而非资源管理器右键创建
离线部署最易被忽略的是 composer.lock 的生成环境一致性——它记录了包的 exact version + dist URL + shasum，一旦在线机器的 PHP 版本、Composer 版本或平台配置（如 platform）与离线机不同，lock 文件就不可复用。务必在与目标环境一致的容器或虚拟机中生成最终 lock 文件。
