Composer如何生成vendor目录离线包_Composer vendor目录离线包生成实践

vendor目录离线包本质是composer install --no-dev后的完整快照

vendor 目录离线包本质是 composer install --no-dev 后的完整快照

说到底，所谓的离线包并没有什么神秘之处，它就是那个你准备好、可以直接扔到生产环境里用的 vendor/ 文件夹。这里面的关键，其实就两点：锁定依赖版本和排除干扰项。整个过程必须严格基于 composer.lock 文件来执行，并且要坚决排除掉那些开发依赖（dev 包）。否则，到了线上环境，你可能会发现私有仓库拉取失败，或者被一些预设的脚本给卡住。如果在本地生成时忘了加 --no-dev 这个参数，那么像 phpunit、phpstan 这类只在开发阶段用到的工具包也会被一并打包进去。它们不仅会显著增加包的体积，更棘手的是，可能会因为生产环境缺少某些PHP扩展，导致自动加载（autoload）直接报错。

具体该怎么操作呢？这里有几个明确的步骤：

• 首先，确认项目根目录下存在一个有效的 composer.lock 文件（这意味着你已经运行过 composer update 或 composer install）。
• 然后，执行这条核心命令：composer install --no-dev --optimize-autoloader --ignore-platform-reqs。
• 其中，--optimize-autoloader 参数会生成一个 vendor/composer/autoload_classmap.php 文件，它能将类名与文件路径的映射关系固化下来，从而减少运行时文件查找的开销。
• 而 --ignore-platform-reqs 参数则非常实用，它能帮你绕过本地PHP版本或扩展与目标环境不一致所引发的安装中断。比如，你本地开发用的是PHP 8.2，但生产服务器还跑在7.4上，这个参数就能避免因此导致的安装失败。

私有包（GitLab/GitHub）必须用 dist 模式打离线包

如果你的 composer.json 里引用了私有仓库（比如类似 "my/package": "dev-main" 这样的定义），Composer默认会采用 source 模式——也就是去克隆整个Git仓库。这在完全离线的环境里是行不通的，而且打包时通常不会包含 .git 目录，这会导致后续在离线环境执行 composer install 时失败。

解决这个问题的核心思路，是强制所有依赖包都通过 dist 模式（即下载压缩包）来获取：

• 可以在运行命令前设置环境变量：COMPOSER_PREFERS_DIST=1。
• 或者在 composer.json 配置文件中明确写上："prefer-stable": true, "prefer-dist": true。
• 如何验证是否生效？安装完成后，去检查 vendor/my/package/ 目录下是否存在 .git 文件夹；如果没有，就说明成功了。
• 如果发现某个包依然走了 source 模式，可以检查它在 composer.lock 文件里的 "source" 字段是否还存在。一个彻底的解决办法是：删除现有的 composer.lock 和 vendor/ 目录，然后重新执行 composer update --prefer-dist。

打包前务必清理无用文件，否则体积暴涨

一个未经处理的 vendor/ 目录里，常常“藏”着大量运行时非必需的文件：测试用例、文档、示例代码、.git 目录，以及未压缩的源码包。例如，lara vel/framework 包里的 tests/ 目录就可能超过30MB。如果不做清理，离线包的体积很容易翻倍，不仅传输耗时，还可能增加解压失败的风险。

这里推荐一组在Linux/macOS下使用的组合清理命令：

find vendor -name "*.md" -o -name "*.txt" -o -name "tests" -o -name "Tests" -o -name ".git" | xargs rm -rf
find vendor -name "phpunit*" -o -name "phpstan*" -o -name "psalm*" | xargs rm -rf
rm -rf vendor/bin/*

需要特别注意：vendor/bin/ 目录下的可执行文件，通常像 phpstan 这类开发工具线上并不需要。但是，如果你的项目依赖了像 lara vel/sail 或 spatie/lara vel-backup 这类包，并且需要用到它们提供的命令行工具，那么对应的二进制文件就必须保留。

离线部署时 composer install 必须加 --no-scripts

很多Composer包会在 post-install-cmd 这类事件中注册脚本，里面可能写死了要执行 php artisan optimize 或 npm run dev 这样的命令。在离线环境里，很可能缺少Node.js或Lara vel命令行工具，这就会导致安装过程卡住甚至失败。这并非Composer的bug，而是其设计如此——它本身并不区分“在线初始化安装”和“离线复用已有包”这两种场景。

因此，在离线环境部署时，正确的命令应该是：

composer install --no-dev --no-scripts --no-interaction

这里有几个常见的陷阱需要警惕：

• 漏掉 --no-scripts 参数：如果部署时看到类似 Script @php artisan package:discover handling the post-autoload-dump event returned with error code 1 的错误，基本就是这个问题。
• --no-interaction 参数也必须带上，否则像 symfony/flex 这样的包可能会在安装时交互式地询问配置，这在无人工值守的部署中会导致失败。
• 绝对不要在离线服务器上尝试运行 composer update —— 没有网络连接，必然会报 Could not fetch https://repo.packagist.org/packages.json 这类错误。

说到底，最可靠的离线部署流程，是把打包好的 vendor 目录视为一个纯粹的、静态的构建产物，而不是期望在运行时去动态生成它。整个过程中，锁文件版本、dist模式、清理策略这三者必须作为一个整体来同步验证，缺一不可。任何一个环节的疏忽，都可能在线上引发难以察觉的静默失败（silent failure）。