离线时 composer install 失败的根本原因是无本地缓存机制且依赖 composer.lock 文件；必须先联网执行 install/update 生成完整 lock 文件并保留 vendor 目录，离线时仅靠 lock 文件即可还原环境。
离线时 composer install 报 Could not fetch packages 怎么办
根本原因不是网络断了，而是 Composer 默认只从 packagist.org（或配置的远程源）拉包，没本地缓存机制。它不自动用已下载过的 .zip 或 .tar 包，除非你提前告诉它“这些包我认得”。
- 必须在有网时先完整执行一次
composer install或composer update，让 Composer 下载所有依赖到vendor/并生成composer.lock -
composer.lock是关键——它锁定每个包的 exact commit hash 和 dist URL，离线时靠它还原一致环境 - 别删
vendor/后再离线运行composer install，那等于没带“货”就上路
如何配置本地仓库让 composer require 也能离线加包
想在离线机器上新增一个包？光有 composer.lock 不够，得让 Composer 知道去哪找这个包的代码。最稳的方式是搭一个本地 packagist 镜像，但更轻量的做法是用 path 类型仓库。
- 把目标包的源码（含
composer.json）放到本地某路径，比如./packages/my-utils - 在项目根目录的
composer.json里加仓库配置："repositories": [ { "type": "path", "url": "./packages/my-utils" } ] - 然后运行
composer require vendor/my-utils:dev-main（注意用dev-*分支名，path仓库不走版本约束逻辑） - ⚠️ 坑：如果包里有
autoload配置，确保路径对得上；path仓库不会自动dump-autoload，装完要手动跑composer dump-autoload
composer create-project 离线失败的真正原因和绕过方法
这个命令默认会连远程源查模板项目元信息，哪怕你指定了本地 .zip 路径，它仍可能尝试访问 packagist。直接失败。
- 别用
create-project离线初始化，改用git clone+composer install - 如果只有 zip 包，先解压，进目录删掉
composer.lock（防止锁住远程地址），再手动运行composer install --no-interaction --prefer-dist - 关键参数：
--prefer-dist强制走 dist 包（即 zip/tar），避免触发 source 克隆；--no-interaction防止卡在交互提示 - 若项目用了
scripts（如post-install-cmd），确认这些脚本不依赖外网（比如 curl 某个 API）
为什么 composer update 在离线时基本不可行
update 的本质是重新解析依赖树、查最新可用版本、比对约束条件——这一步必须联网访问仓库元数据。离线时它连包名都 resolve 不出来。
- 离线场景下，
composer update应视为禁用操作；唯一安全的是composer install（且前提是composer.lock存在且完整） - 如果真要换版本，必须在有网机器上
update→ 提交新的composer.lock→ 同步 lock 文件到离线机 - 注意：不同 Composer 版本（如 2.2 vs 2.5）生成的
lock文件结构略有差异，离线机的 Composer 版本不能低于生成 lock 的机器
离线最脆弱的一环其实是人——容易下意识敲 update 或删掉 vendor 再重装，而忘了 lock 文件才是离线世界的地图。只要它在，路径就没错。
