离线依赖的本质是让 composer install 不依赖实时网络拉包，需提前固化所有依赖及元数据，CI 环境仅本地还原：生成完整 vendor/ 和 composer.lock、缓存 vendor/ 及 archives/、设 COMPOSER_DISABLE_NETWORK=1、确保 PHP 版本严格一致、用 path 仓库替代私有 vcs 包。

CI/CD 中 composer install 总是失败，因为没网或源不稳定

离线依赖的本质不是“完全不联网”，而是让 composer install 不依赖实时网络拉包。关键在提前把所有依赖（含递归依赖）和元数据固化下来，CI 环境只做本地还原。

常见错误现象：composer install 卡在 Installing dependencies from lock file 后报 Connection refused 或超时；或因镜像源临时不可用导致构建飘红。

• 必须在有网、环境干净的机器上运行 composer install --no-dev --prefer-dist --optimize-autoloader，生成完整 vendor/ 和可复用的 composer.lock
• 把整个 vendor/ 目录（非仅 composer.lock）打包进 CI 构建上下文，例如通过 git add vendor（不推荐）或更稳妥地用构建产物缓存（如 GitHub Actions 的 actions/cache 缓存 vendor/ 目录）
• CI 脚本里禁用网络：运行前设 COMPOSER_DISABLE_NETWORK=1，再执行 composer install --no-dev --ignore-platform-reqs，强制走本地 vendor/ 和 lock 文件

composer.lock 里没包含 dist URL，离线时还是去下载

这是因为默认 composer.lock 只记录包名、版本、哈希，不固化 dist 包地址。离线还原时，Composer 仍会尝试从 dist.url 下载——哪怕你本地已有 zip。

解决点很具体：用 composer archive 或第三方工具预打包，或者改用 --prefer-dist + 提前下载并重写 lock 文件。

Academic Composer Upload

辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

下载

• 在构建机上跑一次 composer install --prefer-dist，确保所有包以 zip 形式落在 vendor/composer/archives/（Composer 会自动缓存）
• 把 vendor/composer/archives/ 整个目录打进 CI 缓存，并在 CI 启动时设环境变量 COMPOSER_CACHE_DIR=/path/to/cached/archives
• 验证是否生效：CI 中加一步 ls -la vendor/composer/archives/，确认 zip 文件存在且非空

PHP 版本或扩展不一致导致 --ignore-platform-reqs 后 autoload 失败

离线安装常配合 --ignore-platform-reqs 绕过 PHP 版本、扩展检查，但 autoloader 生成阶段仍会按当前 PHP 环境编译优化，若 CI 的 PHP 小版本或 opcache 配置和本地开发机不同，vendor/autoload.php 可能无法加载或报 Class not found。

• CI 镜像必须与开发环境 PHP 版本严格一致（包括 php -v 输出的小版本号，如 8.1.23 而非只写 8.1）
• 禁用 opcache 编译优化：CI 中运行 composer dump-autoload --optimize --no-dev 前，先设 OPCACHE_ENABLE=0 或在 php.ini 里关掉 opcache.enable
• 如果用了 classmap 或 psr-4 映射，检查 composer.json 中 autoload 段路径是否为相对路径，避免因 CI 工作目录不同导致映射失效

Git 子模块或私有包在离线模式下无法解析

Composer 默认对 vcs 类型仓库（如 GitLab 私有库、GitHub 私有 repo）会在 install 时动态 clone，离线时直接报 Failed to clone ... git@...。这不是网络问题，而是机制问题。

核心思路：把私有包也当作“依赖”提前下载好，用 path 类型仓库替代 vcs。

• 在构建机上把私有包 clone 到本地目录，比如 ./packages/my-private-lib
• 在项目 composer.json 中添加仓库配置：

  {"type": "path", "url": "./packages/my-private-lib"}

  ，并确保该包的 version 字段和 require 中声明的版本一致
• 重新运行 composer update my-private-lib，它会把本地路径写入 composer.lock，之后离线 install 就不再触发 Git 操作

离线依赖最麻烦的从来不是下载本身，而是 Composer 在不同阶段（解析、下载、解压、autoload 生成）对环境的隐式依赖——PHP 版本、扩展、文件权限、工作目录、甚至时区设置，都可能让看似“已缓存”的 vendor 目录在另一台机器上静默失效。