Composer如何在离线环境下使用？（本地仓库配置）

离线时 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 文件才是离线世界的地图。只要它在，路径就没错。