一个接口在测试环境跑了三周,发布到生产之后所有请求 500。日志里只有一句「某个配置项为空」。代码里的读法是 env('PAYMENT_KEY'),本地和测试都有值,生产的 .env 里也明明写了。最后发现是发布脚本加了一行 php artisan config:cache:缓存之后框架不再加载 .env,配置以外的位置调用 env() 只能拿到空值。

同一次发布还有第二处顺序问题。脚本先切了软链,让新代码开始接流量,然后才跑数据库迁移。新代码依赖一个还没加上的列,请求在迁移完成前的几十秒里全部报错。两件事都不是「代码写错」,而是发布流程里两个默认假设不成立:配置缓存会改变 env() 的行为,代码上线和数据变更不是同一时刻完成的。

这篇讲上线这一层:配置怎么缓存、目录怎么组织、Nginx 和 FPM 怎么配、发布的每一步按什么顺序、健康检查查什么、日志写到哪里、出问题怎么退回去。前面五篇的代码在这篇之后才算真正能交付。

.env 与 config:cache 的边界

.env 是本地环境变量文件,框架启动时由 Dotenv 读入。读入之后,config/ 下的配置文件通过 env() 取值,其它代码通过 config() 取值。这条链路的关键是:env() 只在配置加载阶段有意义。

config:cache 把所有配置文件执行一遍,把结果序列化成 bootstrap/cache/config.php。之后每个请求直接读这个数组,不再执行配置文件,也不再加载 .env。所以缓存之后再调用 env('PAYMENT_KEY'),拿到的是 null,而不是环境文件里的值。

业务代码里不要直接调用 env()。所有环境变量都要先落到 config/ 下的某个配置项,业务代码只读 config()。这样开不开配置缓存,行为都一致。已经有项目在控制器里写 env() 的,发布前全局搜一遍。

正确的做法是加一层配置。比如在 config/services.php 里写 'payment_key' => env('PAYMENT_KEY'),业务代码用 config('services.payment_key')。配置缓存之后,config() 读的是缓存数组,值仍然在;.env 改了则必须重新执行 config:cache,否则缓存里的旧值不会变。

这也解释了另一个常见现象:运维在服务器上改了 .env 的数据库密码,重启 FPM 后应用仍然连不上。因为配置缓存还在,.env 根本没被读。改完环境变量必须执行 php artisan config:cache,或者临时 config:clear 调试。这条纪律要写进发布手册,不能靠记忆。

那到底要不要缓存配置?要。缓存省掉了每个请求解析配置文件的开销,生产环境应该开。代价是把「改配置」变成一次显式操作,而不是改文件就生效。这个代价换来的是行为可预测,值得。

releases 与 current:软链发布

不要直接把代码覆盖到正在服务的目录。覆盖过程中,部分文件已经是新的、部分是旧的,autoload 可能指向不存在的类,正在处理的请求会拿到半套代码。正确做法是每次发布建一个新目录,装完、迁完,再用一个软链原子切换。

/srv/cms/
  releases/
    20261107103000/
    20261107120000/
  shared/
    .env
    storage/
  current 指向 releases/20261107120000

releases 下每次发布一个带时间戳的完整目录,shared 放跨版本共享的 .env 和 storage,current 是一个符号链接,指向当前生效的 release。Nginx 的 root 始终写 /srv/cms/current/public,切换时只改链接,不重启 Nginx。

新 release 的 storage 要指向共享目录,通常用软链:ln -s /srv/cms/shared/storage /srv/cms/releases/20261107120000/storage。这样日志、上传文件、缓存不会随版本切换丢失。.env 同理,从 shared 链过去,避免每次发布复制一份、改一处漏一处。

切换命令本身只有一行:

ln -sfn /srv/cms/releases/20261107120000 /srv/cms/current

-sfn 三个参数分别是「符号链接、强制覆盖、把已存在的链接当成文件而不是目录」。少了 -n,如果 current 已经是一个指向目录的链接,ln 可能会在链接内部再建一个链接,出现 current/releases/... 这种套娃路径。切换后用 readlink -f /srv/cms/current 确认指向正确。

权限要在发布前处理好。整个 release 目录对运行用户可读,storage 和 bootstrap/cache 可写;部署用户和 FPM 用户通常不是同一个,靠用户组加 setgid 目录来共享写权限,比直接 chmod 777 安全得多。

Nginx、FPM 与 OPcache

生产环境的 Nginx 配置在第 1 篇给过一个最小版本。配合软链发布,有两处需要改。第一处是 root 指向 current/public;第二处是 SCRIPT_FILENAME 用 $realpath_root,让 FPM 拿到解析软链之后的真实路径:

root /srv/cms/current/public;

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}

$document_root 是配置里写的路径,$realpath_root 是解析之后的真实路径。用前者时,OPcache 会按 current/public/index.php 缓存,切换软链后路径字符串没变但文件内容变了,缓存是否失效依赖时间戳检查;用后者时每次切换路径都变,缓存键跟着变,行为更可预测。

OPcache 把编译后的字节码留在共享内存里,省掉每个请求的编译。生产配置通常开三个开关:opcache.enable=1、opcache.memory_consumption 给到 128 或 256 MB、opcache.max_accelerated_files 给到 20000 以上。项目文件多、类多时,缓存装不下会频繁淘汰,命中率下降,表现为发布后一段时间响应变慢。

opcache.validate_timestamps=0 是很多人推荐的生产配置,它让 OPcache 不再检查文件修改时间,性能最好;代价是改了代码必须重启 FPM 才生效。配合软链发布,每次切换后执行 systemctl reload php8.3-fpm,新进程加载新路径。反过来,如果你在服务器上直接改文件调试,这个开关会让改动「不生效」,很容易误判成发布失败。

FPM 池的进程数按内存算,别照抄别人的值。一个普通的 Laravel 进程常驻几十兆,跑起来峰值可能到一百多兆;pm.max_children 乘单进程内存不能超过机器可用内存,还要给系统和数据库客户端留余量。pm 用 dynamic 适合大多数业务,固定流量高峰的场景可以考虑 static,省掉进程调度开销。

一次发布按什么顺序执行

发布脚本的每一步都有前置条件,顺序错了就会出现「代码上了、表还没改」这类窗口。一个可用的顺序如下:

软链发布的执行顺序
拉取新代码
安装生产依赖
执行数据库迁移
生成配置与路由缓存
切换 current 软链
重启队列与 FPM
跑健康检查

逐条说明。拉取到新的 release 目录,先装依赖:composer install --no-dev --prefer-dist --optimize-autoloader。生产依赖以提交进仓库的 composer.lock 为准,require-dev 里的测试和静态分析工具不装;加 --no-dev 不装测试工具,减少体积和攻击面;--optimize-autoloader 生成 classmap,减少运行时查找。装依赖时旧版本还在服务,失败也不影响线上。

接着跑迁移:php artisan migrate --force。生产环境会二次确认,--force 跳过确认,让脚本能非交互执行。这一步必须发生在切换软链之前,而且迁移本身要向后兼容——新代码不能依赖「还没加上的列」,旧代码也不能因为「新加的列」而报错。第 3 篇讲的「先加可空列、再回填、最后加约束」就是为了满足这个条件。

然后生成缓存:php artisan config:cache、route:cache、view:cache。这些命令写的是新 release 目录下的 bootstrap/cache 和 storage/framework/views,此时还没切流量,出错可以停下来修,不会影响用户。

再切换软链,让新代码开始接流量。紧接着执行 php artisan queue:restart,让 worker 处理完当前任务后退出并重启,加载新代码;再 systemctl reload php8.3-fpm,让 OPcache 用新路径重新编译。最后用健康检查确认新版本真的能服务,失败就切回上一个 release。

顺序里有两个常见错误。切流量之后再迁移,会有一段「新代码撞旧表」的窗口;先重启 worker 再切软链,worker 加载的是旧目录的代码,等于白重启。把「迁移在切流量前、重启在切流量后」记成一条规则,能避免大部分发布事故。

缓存命令与它们的坑

发布时常用的缓存命令有四个,各有作用范围:

命令缓存什么什么时候必须重跑
config:cache合并所有配置文件改 .env 或 config/ 之后
route:cache编译路由表增删路由之后
view:cache预编译 Blade 模板改模板之后
event:cache事件与监听器映射改监听器注册之后

旧版本里 route:cache 有一个硬限制:闭包路由无法被序列化,缓存命令会直接报错退出。本机 Laravel 12.71.0 实测已经没有这个限制:第 1 篇那个用闭包写的 /api/health 仍然可以 route:cache,命令输出 INFO Routes cached successfully.,之后请求仍返回 200。不过部署时仍建议把健康检查写成控制器方法,便于复用与测试,也不必依赖版本行为。

对应的清理命令是 config:clear、route:clear、view:clear、event:clear,以及一把清空的 optimize:clear。排查「改了配置不生效」时,先执行 config:clear 再请求一次,能立刻区分「配置写错」和「缓存没更新」。

缓存文件写在 release 目录里,切换软链后自然会用新目录的缓存。但 bootstrap/cache 要保持每个 release 独立,只共享 storage;如果把它软链到共享目录,新旧版本会共用同一份缓存,切换瞬间可能出现路由表和代码不匹配。

健康检查:/up 与就绪检查

Laravel 12 在 bootstrap/app.php 的 withRouting 里有一项 health: '/up',它注册一个内置的健康检查路由,返回 200,用来回答「进程还在不在」。负载均衡和进程守护用这个地址做存活探测,够用且便宜。

但它不检查数据库、不检查 Redis,也不检查队列。真正上线时还需要一个「就绪检查」(readiness),回答「这个实例现在能不能接业务」。两者要分开:存活检查失败就重启进程,就绪检查失败只是把它从负载均衡里摘掉。

自定义就绪检查写成控制器,便于复用和测试。控制器里对每个依赖做一个短超时的探测,任何一项失败返回 503:

public function ready()
{
    $checks = ['db' => 'ok', 'cache' => 'ok'];

    try {
        DB::select('select 1');
    } catch (\Throwable $e) {
        $checks['db'] = 'fail';
    }

    try {
        Cache::store('redis')->put('health:probe', '1', 5);
    } catch (\Throwable $e) {
        $checks['cache'] = 'fail';
    }

    $ready = ! in_array('fail', $checks, true);

    return response()->json([
        'status' => $ready ? 'ready' : 'not_ready',
        'checks' => $checks,
    ], $ready ? 200 : 503);
}

探测要有超时上限。数据库连接默认可能等几十秒,健康检查自己先超时,负载均衡会以为实例死了。给连接配置一个短的 connect_timeout,或者在探测外层加时间预算,别让健康检查变成压垮实例的最后一根稻草。

调用与实测返回:

curl -i http://127.0.0.1:8030/up
curl -i http://127.0.0.1:8030/api/health/ready

本机实测第一个返回 200 和 Application up。第二个返回 503 和 {"status":"not_ready","checks":{"db":"ok","cache":"fail"}}:本机没有 Redis,数据库检查是 ok,缓存检查是 fail,正好对应「停掉 Redis」那一半。等 Redis 可用后,同一控制器会返回 200 和 {"status":"ready","checks":{"db":"ok","cache":"ok"}}。

日志:写到哪里,带什么信息

日志通道在 config/logging.php 里配置,默认的 stack 会把日志写到 storage/logs/laravel.log。单文件适合小项目,但文件会一直涨;daily 按天切分并保留指定天数,是更常见的选择。

容器化部署通常不写文件,而是把日志打到标准错误,由容器运行时收集。这时把 LOG_CHANNEL=stderr 配好,应用日志和系统日志走同一条采集链路,不用再挂卷、也不用担心磁盘被写满。无论哪种方式,都要给日志目录设置权限和轮转,磁盘写满导致整站 500 是很典型的事故。

日志内容要有请求 ID。第 2 篇写的中间件会给每个请求生成一个 ID 并放进响应头,再把同一个 ID 写进日志上下文,前端报错时带上它,后端就能直接定位那一条:

Log::withContext(['request_id' => $requestId]);
Log::warning('payment callback failed', ['order_id' => $orderId]);

日志里不要出现密码、令牌、完整身份证号和请求体全文。这些内容一旦进了日志文件,就会跟着备份、监控和排查记录扩散出去。需要排查请求内容时,只记录字段名和长度,或者做脱敏后再写。

日志级别也要控制。生产环境用 warning 或 error,不要长期开 debug;debug 日志会在高峰期产生巨大的写入量,既拖慢请求,也会掩盖真正的错误。需要临时排查时再调低,查完改回去。

回滚:切回去,但别指望数据库

软链发布最大的好处是回滚便宜:把 current 指回上一个 release,重启 FPM 和队列,几十秒就能恢复。保留最近三到五个 release,确认新版本稳定后再清理更早的目录。

ln -sfn /srv/cms/releases/20261107103000 /srv/cms/current
php artisan queue:restart
systemctl reload php8.3-fpm
curl -f http://127.0.0.1:8000/up

但代码能回滚,数据库不一定。如果新版本已经执行了删除列、改列类型的迁移,旧代码回去之后会对不上表结构。这就是为什么迁移要遵守「扩展与收缩」:加列、回填、切读、删旧列分多次发布,任何一次发布失败,旧代码都还能在当前的库结构上运行。

回滚之后要补一件事:确认队列里的任务没有用到新版本的类。旧 worker 重启后如果取到一条 payload 里写着新类名的任务,会反序列化失败。发布时如果有新任务类,最好在新版本稳定一段时间后再让旧版本下线,或者保证旧代码里也有这个类的兼容实现。

回滚不是失败,是发布流程的一部分。真正危险的是「不敢回滚,在现场改代码」。现场改代码没有测试、没有记录,改完之后线上跑的是哪个版本都说不清。宁可切回上一个版本,再在本地定位。

现象、原因与第一步

现象真实原因第一步查什么
上线后全站 500,提示配置为空config:cache 后仍用 env() 读配置全局搜 env(;看 bootstrap/cache/config.php 是否存在
改了 .env 不生效配置缓存未重建php artisan config:clear 后重试
新路由 404路由缓存还是旧的route:clear;确认发布脚本跑了 route:cache
上传文件 404storage:link 没执行,或链接指向旧 release看 public/storage 是否指向当前共享目录
502 Bad GatewayFPM 未 reload,或 socket 路径与配置不一致systemctl status php8.3-fpm;看 Nginx error log
发布后任务行为没变漏了 queue:restart看 worker 启动时间;执行重启后再观察
部分机器正常、部分 500多台机器发布不同步,OPcache 仍是旧代码逐台确认软链指向与 FPM reload 时间
健康检查通过但业务报错只探了存活,没有就绪探测加数据库与缓存探测;看 503 的 checks
切软链后请求短暂报错切换与 FPM reload 之间有窗口确认脚本顺序;必要时先 reload 再切

边界与代价

软链发布适合单机或少量应用服务器。机器到三五台时,每台都要按同样顺序执行,靠人记容易漏;这时候需要发布编排工具,或者把脚本收敛成一个可重复执行的命令。机器再多,数据库迁移就变成整个集群的同步点,发布窗口要从「分钟级」拉到「小时级」。

「无停机」不是一个开关。软链切换接近原子,但 FPM reload 会有短暂的新旧进程交替,OPcache 冷启动也会让前几个请求变慢。要做到真正的零停机,需要蓝绿部署或滚动发布:新版本先起一组实例、健康检查通过后再切流量,旧组保留一段时间。这套做法的成本是双倍资源和一个能协调流量的入口。

上 Octane 或 RoadRunner 之后,发布方式要改。常驻进程不会因为软链切换自动加载新代码,必须执行 php artisan octane:reload 或重启对应进程;同时前面提过的状态泄漏问题会放大,发布前的回归测试要覆盖「连续请求之间是否串数据」。性能提升是真实的,运维复杂度也是真实的。

配置缓存、路由缓存、OPcache 三者叠加,把「改一个文件立刻生效」变成了「必须按流程重建缓存并重启」。这套纪律在团队小的时候显得繁琐,但它是线上行为可预测的前提。真正的代价不是命令多,而是漏一步之后现象很隐蔽:本地永远正常,线上只在特定条件下错。

当天能自己验证的练习

  1. 在控制器里写一个 env('DEMO_KEY'),执行 php artisan config:cache 后请求,确认返回空;再改成 config('services.demo_key'),重复一次,对比结果。
  2. 建两个 release 目录,用 ln -sfn 切换 current,用 readlink -f 确认指向;故意少写 -n,观察是否出现套娃路径。
  3. 用 curl -i /up 和自定义就绪接口分别请求,停掉 Redis 后再请求一次,确认前者仍 200、后者变 503。
  4. 故意留一个闭包路由,执行 php artisan route:cache,记录报错原文,再改成控制器方法后重试。
  5. 发布后把 current 切回上一个 release,重启 FPM 与队列,用健康检查和一条业务请求确认回滚成功。

小结

三句话:env() 只在配置文件中使用,缓存之后业务代码一律读 config();发布顺序是迁移在切流量之前、队列重启和 FPM reload 在切流量之后;健康检查分存活和就绪两种,回滚能切代码但切不回已经改掉的数据结构。

这一组六篇到这里收束:从建项目、路由与中间件、数据访问、鉴权会话、队列定时,到最后的发布。它们共同回答一个问题——一个 PHP 服务从空目录到能上线,中间需要哪些固定的层,每层的边界在哪。接下来可以按自己的项目挑一环深入:数据库性能、可观测性、容器化,或者把这套流程固化成一条可重复执行的发布脚本。