如何在生产环境中使用Composer部署PHP代码

生产环境绝不能直接运行 composer install，必须在构建阶段完成依赖安装并整体同步代码包

在生产服务器上执行 composer install，听起来像是个省事的捷径，对吧？但真相是，这绝非一个可以权衡的选项，而是一条必须坚守的底线。直接在生产环境拉取依赖，几乎是引发 502 错误、类找不到、权限混乱乃至密钥泄露等一系列问题的“直通车”。

为什么生产机上绝对不能跑 composer install

表面上的便利，背后隐藏着三类足以让部署失控的硬伤：

• 权限混乱：那个经典的 file_put_contents(./composer.json): failed to open stream: Permission denied 错误，根源往往不是 Composer 本身，而是 Web 服务用户（比如 www-data）对 vendor/ 目录或 composer.lock 文件没有写入权限。排查这类问题所耗费的时间，通常会远超最初的预估。
• 环境漂移：一句 Your platform does not meet the requirements 就可能让部署戛然而止。想象一下，本地开发用的是 PHP 8.2，而线上环境还是 8.1，platform-check 会毫不留情地中断整个流程，导致服务不可用。
• 安全暴露：这才是最危险的一环。只要 Nginx 配置稍有疏漏，例如未禁止对 .env 文件的访问，攻击者可能在几秒钟内就下载到包含数据库密码、API 密钥在内的所有敏感信息。

composer install 必须带的三个参数

在构建阶段执行安装时，有三个参数不是“建议组合”，而是彼此互锁、缺一不可的最小安全集合。漏掉任何一个，都可能导致服务响应变慢、偶发 500 错误，甚至让 CI/CD 流水线卡住。

• --no-dev：这个参数的作用是跳过 require-dev 部分的所有开发依赖包，比如 phpunit 或 symfony/debug-bundle。如果不加，这些包不仅会被加载，还可能通过 autoload.php 暴露调试入口，同时拖慢生产环境的类加载速度。
• --optimize-autoloader：它的价值在于生成 vendor/composer/autoload_classmap.php 文件，将类名直接映射到文件路径。实测表明，这能将单次类加载的平均时间从 1.2ms 大幅降至 0.05ms。在高并发场景下，不加这个参数，autoload 机制本身就可能成为 I/O 瓶颈。
• --no-interaction：这个参数是为了防止安装过程被交互式提示卡住。例如，当 Composer 询问 “Do you want to store credentials for github.com?” 时，在无人值守的 Docker 构建或 CI 环境中，整个进程就会因等待输入而超时失败。

Nginx 必须显式禁止访问的路径

很多配置依赖 try_files $uri $uri/ /index.php?$query_string; 来处理路由，但这行指令只管转发，不负责拦截对真实文件的直接访问。真正起防护作用的，是下面这些具体的 location 规则：

立即学习“PHP免费学习笔记（深入）”；

• location ~ /\.(env|json|lock|git|hg|svn)$ { deny all; }：这条规则旨在拦截所有以点号开头、具有特定后缀的配置文件和版本控制元数据文件。
• location ^~ /vendor/ { return 403; }：使用 ^~ 前缀匹配，可以确保该规则优先于类似 location ~ \.php$ 的规则生效，从而彻底封死对 vendor/ 源码目录的遍历访问。
• location = /composer.json { return 403; }：对于根目录下的关键文件，如 composer.json，需要使用精确匹配（=）来单独封锁，因为 ^~ 前缀匹配对精确路径不生效。

PHP-FPM 权限和 opcache 的关键检查点

很多 502 Bad Gateway 错误的根源，其实并不在 Nginx 或网络层面，而是 PHP-FPM 进程无法读取到它需要的类文件。以下几个检查点至关重要：

• 文件系统权限：务必确认 www.conf 中配置的 user 和 group（例如 www-data）对 vendor/、storage/、bootstrap/cache/ 等目录拥有读和执行权限。记住，对于目录而言，执行权限（+x）是进入该目录的前提。
• Socket 权限：如果使用 listen = /run/php/php8.1-fpm.sock 这样的 Unix socket，必须确保其父目录 /run/php/ 允许 PHP-FPM 进程用户写入。否则，一个更直接的方案是改用 listen = 127.0.0.1:9000 来绕过 socket 文件权限问题。
• Opcache 配置：确保 opcache.enable=1 且 生产环境务必设置 opcache.validate_timestamps=0。这意味着，每次代码部署后，必须手动执行 opcache_reset() 或重启 PHP-FPM 服务，否则旧的字节码将继续生效，新代码不会被执行。

最后，也是最容易被忽略的一点，在于构建与部署之间的“交接”。vendor/ 目录必须作为一个完整的、由构建机生成的产物，被整体同步到生产服务器，而不是依靠 rsync 进行差量覆盖。哪怕只遗漏了一个小小的 .php 文件，上线后等待你的就是冰冷的 Class not found。这一步，没有容错空间。