Windows与Linux/macOS的vendor路径差异导致离线部署失败，主因是硬编码反斜杠、autoload路径不兼容及PHP realpath缓存污染；需在目标环境执行install、统一用DIRECTORY_SEPARATOR、清理缓存并配置PHP realpath缓存。
Windows 和 Linux/macOS 的 vendor 路径差异导致离线部署失败
Composer 在离线环境中同步依赖时，如果开发机是 Windows、目标部署环境是 Linux，vendor 目录下某些包的 autoload 逻辑或脚本路径可能硬编码了反斜杠 ，导致 require 或 autoload.php 加载失败。这不是 Composer 本身 bug，而是部分包（尤其含自定义安装脚本或生成器的）在生成路径时未做跨平台适配。
实操建议：
- 检查
vendor/autoload.php是否能被目标系统正常require；若报错如Warning: require(.../vendor/composer/../somepath.php): failed to open stream，说明路径分隔符混用 - 运行
composer dump-autoload --optimize后再打包，它会生成扁平化映射，减少动态拼接路径的环节 - 避免在
post-install-cmd或post-update-cmd中使用__DIR__ . 'sub ile.php'这类写法；统一改用__DIR__ . DIRECTORY_SEPARATOR . 'sub' . DIRECTORY_SEPARATOR . 'file.php' - 若依赖包自身有硬编码路径问题（如旧版
phpunit/phpunit某些辅助类），可临时 fork 并 patch，或锁定兼容版本（如"phpunit/phpunit": "^9.5.26"）
composer install --no-scripts --no-plugins 在离线环境不是万能解
很多人以为关掉脚本和插件就能绕过路径问题，但实际仍可能触发自动加载器生成、classmap 扫描等隐式行为——这些过程内部调用 realpath() 或 scandir()，在跨平台挂载卷（如 Docker 绑定挂载 Windows 主机目录到 Linux 容器）下会返回不一致的路径格式。
实操建议：
- 离线打包前，务必在与目标环境一致的 OS 上执行
composer install --no-dev --optimize-autoloader；不要在 Windows 上生成再拷到 Linux - 确认
composer.lock中的content-hash和platform字段是否匹配目标环境；比如"platform": {"php": "8.1.20"}若不一致，autoload_classmap.php可能漏掉某些文件 - 检查
vendor/composer/autoload_*.php文件里是否有类似dirname(__DIR__) . '/src\Something.php'的字符串；有则说明该包未适配 PSR-4 自动发现，需手动干预或换包
用 COMPOSER_HOME 和 COMPOSER_CACHE_DIR 隔离离线缓存路径
默认情况下，Composer 会把下载的 zip 包和解压缓存存在用户主目录（如 C:UsersxxxAppDataRoamingComposer 或 ~/.composer），一旦开发机和构建机用户不同、或路径权限受限，composer install 就会因找不到缓存而卡住或报错 Could not fetch https://.../package.zip ——即使你已提供完整 vendor 目录。
实操建议：
- 离线构建前，在构建机上设置环境变量：
COMPOSER_HOME=/tmp/composer-home和COMPOSER_CACHE_DIR=/tmp/composer-cache，确保路径存在且可写 - 用
composer install --no-interaction --prefer-dist --ignore-platform-reqs启动，跳过交互和平台校验，防止因 PHP 版本或扩展缺失中断 - 如果必须复用本地
vendor，先运行composer clear-cache再设缓存路径，否则旧缓存可能干扰 hash 校验
PHP opcache.enable 和 realpath_cache_size 影响离线 autoload 行为
在容器或 CI 环境中，PHP 的 realpath 缓存可能记住开发机的路径（如 C:project endor...），即使代码已复制到 /app/vendor，require 仍尝试访问原路径，报错 No such file or directory。这和 Composer 关系不大，但属于离线部署时高频踩坑点。
实操建议：
- 部署后首次运行前，加一句
php -r "clearstatcache(true);"清除 realpath 缓存 - 在
php.ini中设realpath_cache_size = 4M（默认 16K 太小）、realpath_cache_ttl = 60，避免缓存污染长期残留 - 若用 OPcache，确认
opcache.enable=1且opcache.validate_timestamps=1（离线环境可设为 0，但需重启 PHP 进程生效）
跨平台离线部署最麻烦的从来不是下载或解压，而是路径在 autoload、classmap、脚本执行、甚至 PHP 内部缓存里的多层渗透——每个环节都可能把开发机的“气味”带过去。盯住 vendor/autoload.php 和 realpath() 的输出，比反复重装 Composer 有用得多。
