离线依赖的本质是让 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 文件。
- 在构建机上跑一次
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 操作
