项目是这么起的:执行 composer create-project laravel/laravel cms,本机跑 php -S 起服务,浏览器打开返回一段 JSON,一切正常。把代码传到服务器,Nginx 配好以后打开域名,直接 404,storage/logs/laravel.log 里什么都没有。
排查了两个小时,最后发现 Nginx 的 document root(网站根目录)指到了项目根目录。Laravel 的入口文件不在根目录,而在 public/index.php。Nginx 在根目录找不到默认入口,就自己返回了 404,PHP 根本没有被调用,所以应用日志一片空白。这类“框架没报错、Nginx 先报错”的现象,第一次遇到很容易往代码上找。
这篇从一个空目录开始,把「装依赖、建项目、写第一个接口、用三种方式跑起来、上线后不 404」走一遍。PHP 语法不在本篇范围,那部分在语言方向里单独讲;这里只关心一个请求怎么进到框架、又怎么出去。
为什么后端从框架讲起
会写 PHP 不等于能交付一个后端服务。语言层面解决的是变量、函数、类、数组这些表达问题;真正上线还要处理请求分发、参数校验、数据库连接、身份认证、后台任务、日志和部署。每一项单独看都不难,难在它们要按固定顺序组合,任何一环漏掉边界都会变成线上问题。
框架(framework)做的事情,就是把这些通用环节固化成一套约定:请求进来走固定的管线,按路由表找到处理代码,处理完统一生成响应,出错走统一的异常出口。约定带来的是可预测性——出了问题有固定的排查顺序,而不是每次靠猜。
Laravel 是目前 PHP 生态里使用面最广的全栈框架,本文的技术口径是 Laravel 12、PHP 8.3、Composer 2。Laravel 12 延续了 11 的目录结构,没有 app/Http/Kernel.php,中间件和路由的注册都集中在 bootstrap/app.php。网上很多老教程还在改 Kernel,照抄会找不到文件。
composer create-project laravel/laravel demo "^12.0" 装好 Laravel 12.71.0。下面的命令和返回均在本机 Windows 11 实测;只有 php artisan serve 在本机报 Failed to listen on 127.0.0.1:8031 (reason: ?),HTTP 验证改用等价的 php -S 127.0.0.1:8030 -t public。Laravel 与 Symfony 怎么选
先澄清一个常见误解:Laravel 和 Symfony 不是两套完全独立的东西。Laravel 的 HTTP 请求响应、路由、控制台、事件等底层组件,大量直接使用 Symfony 的库。差别主要在「框架给你多少默认答案」。
| 维度 | Laravel 12 | Symfony 7 |
|---|---|---|
| 上手成本 | 低,装完就能写接口,默认目录清晰 | 偏高,需要先理解组件、Bundle 和配置体系 |
| 默认约定 | 强约定,目录、命名、ORM 都有标准答案 | 弱约定,分层和目录由团队自己定 |
| 数据访问 | Eloquent ORM,Active Record 风格 | Doctrine ORM,Data Mapper 风格 |
| 生态与轮子 | 认证、队列、调度、广播、测试工具齐全 | 组件质量高,但很多能力要自己组装 |
| 长期演进 | 大版本节奏快,升级要跟 | 版本周期长,LTS 更适合长周期系统 |
| 适合场景 | 中小团队快速交付业务系统、API | 大型组织、需要严格分层或组件复用的系统 |
取舍其实很朴素:如果你的团队只有几个人,业务要两个月上线,Laravel 的默认约定能省下大量设计讨论;如果系统预计维护五年以上、团队分工很细、需要把领域层和框架层隔离,Symfony 的克制会更舒服。还有一条现实因素:团队里谁写过什么,往往比框架本身的优劣更能决定结果。
选 Laravel 的理由
默认值合理,认证、队列、调度开箱可用;文档和社区样本多,遇到问题容易搜到答案;适合把精力放在业务而不是基础设施上的团队。
选 Symfony 的理由
组件边界清楚,长期维护和替换成本可控;不强推某一种 ORM 或目录结构,适合已有架构规范的团队;对类型和显式配置的要求更严。
还有一点容易忽略:两者的「耦合方向」不同。Laravel 把大量组件绑在一个统一容器里,写起来顺手,但替换单个组件(比如换掉 ORM)比较费劲;Symfony 的组件可以单独拿出来用,替换成本低,代价是初始装配要自己写不少代码。项目如果只是业务 API,这种差别几乎感受不到;如果系统里有一部分能力要给其他项目复用,差别就会明显起来。
本文后续都用 Laravel 做示例,因为它能把一条完整链路压缩到最少的文件里。理解这条链路之后,换成 Symfony 或别的框架,需要重新学的只是注册方式和目录约定。
环境与依赖清单
一套能跑 Laravel 12 的最小环境,逐项列清楚,缺一项都会在某个时刻报错:
| 组件 | 版本 | 用途 | 缺失时的表现 |
|---|---|---|---|
| PHP CLI | 8.3 | 跑 artisan、Composer、队列 | 命令行直接找不到 php |
| PHP-FPM | 8.3 | 给 Nginx 提供 PHP 进程 | 502 Bad Gateway |
| 扩展 | pdo_mysql、mbstring、openssl、tokenizer、xml、ctype、json、bcmath、fileinfo、curl | 数据库、字符串、加密、框架启动 | 启动时报缺少扩展或类 |
| Composer | 2.x | 安装依赖、生成自动加载 | 无法 create-project |
| MySQL | 8.0 | 业务数据 | 连接被拒或驱动不存在 |
| Redis | 7.x(可选) | 缓存与队列 | 可先用 database 驱动顶上 |
| Nginx | 1.24 以上 | 反向代理、静态文件 | 只能本机访问 |
检查环境不要靠记忆,直接用命令看:php -v 看版本,php -m 列出已装扩展,composer -V 看 Composer 版本,php -r "echo PHP_VERSION;" 确认 CLI 和 FPM 用的是同一个 PHP。最后这条经常被忽略:CLI 是 8.3、FPM 是 8.1 的机器并不少见,本地 artisan 跑得好好的,网页却报语法错误。
工程侧的依赖则由 composer.json 管理。Laravel 12 骨架默认会带上 laravel/framework、laravel/tinker,开发依赖里有 phpunit/phpunit、laravel/pint、mockery 等。composer.lock 必须提交,部署时用 composer install 而不是 update,保证测试和生产装的是同一套版本。
创建项目与目录结构
选一个空目录,执行下面三行。第一行拉取骨架并安装依赖,第二行复制环境文件,第三行生成应用密钥:
composer create-project laravel/laravel cms "^12.0"
cd cms
cp .env.example .env
php artisan key:generate
装完之后先别急着写代码,把目录认一遍。Laravel 的约定都体现在这里:
cms/
app/
Http/Controllers/ 控制器
Models/ 模型
Providers/ 服务提供者
bootstrap/
app.php 应用装配入口
cache/ 框架缓存
config/ 各模块配置
database/
migrations/ 迁移文件
seeders/ 初始数据
public/
index.php 唯一入口
routes/
web.php Web 路由
api.php API 路由(按需生成)
console.php 定时任务与命令
storage/
app/ 应用文件
logs/ 日志
framework/ 会话、缓存、视图缓存
vendor/ 依赖
.env 本地环境变量
几个位置值得单独说明。public/ 是唯一允许暴露给外部的目录,里面只有入口和前端构建产物;.env、vendor/、storage/ 都不能被 Web 直接访问。bootstrap/app.php 是 Laravel 11 起的新装配入口,路由、中间件、异常处理都在这里注册,取代了旧的 Kernel 和 RouteServiceProvider。storage/ 和 bootstrap/cache/ 必须对 PHP-FPM 的运行用户可写,否则第一次访问就 500。
Laravel 12 的骨架默认不包含 routes/api.php。官方推荐执行 php artisan install:api,它会安装 Sanctum、生成 routes/api.php 并自动补上路由注册。如果不想引入 Sanctum,也可以手动创建这个文件,再在 bootstrap/app.php 里加一行 api: 参数,效果一样。
composer create-project 不只下载代码,它会按骨架的 post-create-project-cmd 脚本依次执行复制 .env、生成密钥、创建 SQLite 文件等动作,最后跑一遍 composer install。所以在有脚本钩子的情况下,手动再跑一次 key:generate 并不是必须的,但养成检查 .env 的习惯没有坏处。整个过程依赖网络访问包仓库,公司内网装不动时,配置一个内部镜像源或把构建放到 CI 里,比在服务器上现场下载更可靠。
目录里还有两个常被改坏的地方。storage/ 下的 framework/sessions、framework/cache、framework/views 三个目录必须存在且可写,从压缩包解压时目录可能被丢掉;bootstrap/cache/ 里会生成 packages.php、services.php 等缓存文件,手工删掉不会坏,但目录本身必须存在。部署脚本里通常会补一句 chmod -R ug+rwX storage bootstrap/cache,作用就是把这两处权限修好。
第一个接口:/api/health
健康检查接口(health check)是给运维和监控用的:它不查数据库、不依赖第三方服务,只回答「这个进程还活着」。先写它,可以把「框架能不能启动」和「业务代码对不对」两件事分开排查。
先确认 bootstrap/app.php 里有 api 路由的注册。完整结构大致如下,重点是 withRouting 里的 api 一行:
<?php
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
return Application::configure(basePath: dirname(__DIR__))
->withRouting(
web: __DIR__.'/../routes/web.php',
api: __DIR__.'/../routes/api.php',
commands: __DIR__.'/../routes/console.php',
health: '/up',
)
->withMiddleware(function (Middleware $middleware) {
//
})
->withExceptions(function (Exceptions $exceptions) {
//
})->create();
然后在 routes/api.php 里写路由。注意这个文件里的路由会自动带上 /api 前缀,所以这里写 /health,实际访问地址是 /api/health:
<?php
use Illuminate\Support\Facades\Route;
Route::get('/health', function () {
return response()->json([
'status' => 'ok',
'service' => 'cms-api',
'time' => now()->toIso8601String(),
]);
});
这里用闭包写路由,是为了让示例只依赖一个文件。真实项目里的接口一般写成控制器方法,路由只负责把 URL 映射过去,控制器再调用服务层。健康检查是少数适合留在闭包里的场景,因为它不涉及业务逻辑,也不该去查数据库——一旦健康检查依赖数据库,数据库抖动时监控会把所有实例都判定为不健康,反而放大故障。
写完后先别用浏览器,用 artisan 把路由表打出来,确认前缀和中间件都对:
php artisan route:list --path=api
本机实测输出 11 条 API 路由,其中有一行方法 GET|HEAD、URI 为 api/health,中间件列包含 api 分组。如果这里没有,说明文件没被注册,先查 bootstrap/app.php 的 api: 参数和文件路径,别急着查 Nginx。
启动本地服务后调用(artisan serve 在本机起不来,改用等价的 php -S):
php -S 127.0.0.1:8030 -t public
curl -i http://127.0.0.1:8030/api/health
本机实测返回:
HTTP/1.1 200 OK
Host: 127.0.0.1:8030
Connection: close
X-Powered-By: PHP/8.3.36
Cache-Control: no-cache, private
Date: Sat, 07 Nov 2026 03:50:24 GMT
Content-Type: application/json
X-Request-Id: 83b957a5-6733-4573-b4e6-c4f4bcf61587
Access-Control-Allow-Origin: *
{"status":"ok","service":"cms-api","time":"2026-11-07T03:50:24+00:00"}
Date、time 和请求 ID 是本机 2026-11-07 03:50:24 UTC 的原始输出,没有润色。时间字段每次不同,只要状态码 200 且 JSON 里三个键齐全,就说明从内置服务器到路由再到响应这条链路是通的。三种启动方式,别用错场景
同一个项目有三种跑法,用途完全不同。混用是很多「本地正常、线上异常」的起点。
public/index.php。单进程,改代码即生效,不要用于压测,也不要用于生产。-t public 时,它只把存在的文件当静态文件返回,/api/health 这种不存在的路径会直接 404。要让它转发,必须把入口脚本作为路由脚本传进去。第二种的正确写法是:
php -S 127.0.0.1:8000 -t public public/index.php
最后的 public/index.php 是路由脚本,所有请求都会先经过它。少了这个参数,表现就是首页能开、接口全 404,和第 1 节的事故一模一样,只是换成了内置服务器。
生产环境的 Nginx 配置,关键只有几行。root 必须指向 public,try_files 必须把找不到的路径交给入口:
server {
listen 80;
server_name cms.example.internal;
root /srv/cms/current/public;
index index.php;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}
location ~ /\.(?!well-known) {
deny all;
}
}
这三处各有含义。root 指到项目根目录时,Nginx 会在根目录找 index.php,找不到就 404,而且 .env 可能在某种配置下被当静态文件下载,这是安全事故。try_files 的作用是「文件不存在就交给 index.php」,没有它,/api/health 永远到不了路由。fastcgi_pass 的 socket 路径要和机器上 FPM 实际监听的一致,Ubuntu 与 CentOS 的默认路径不同,改完必须 nginx -t 并 reload。
FPM 侧还有一个参数值得早点知道:pm.max_children 决定同时能处理多少个请求。它不是越大越好,每个 PHP 进程都占内存,进程数要按「可用内存除以单进程峰值内存」来算;同时它又直接等于数据库连接数的上限,因为每个进程处理请求时可能各占一条连接。这个算术在第 3 篇讲连接数时会展开,这里先记住:调大 FPM 进程数之前,先确认数据库接得住。
.env 与 APP_KEY
.env 是本地环境变量文件,框架启动时由 Dotenv 读入,供 config/ 下的配置文件取值。它不进版本库,仓库里只放 .env.example。部署时由运维或发布脚本在服务器上生成真正的 .env。
APP_KEY 是应用密钥,一串 base64 编码的随机值。它用于加密 Cookie、生成签名 URL、加密会话数据。没有它,框架在启动阶段就会抛「No application encryption key has been specified」。生成命令是 php artisan key:generate,它直接改写 .env。
.env 提交进仓库,也不要把 APP_KEY 提交进任何配置文件。密钥泄露意味着别人可以伪造加密 Cookie 和签名链接。多机部署时所有机器必须使用同一个 APP_KEY,否则 A 机发的 Cookie 到 B 机解不开,表现为「刷新就掉登录」。环境文件里另外三个值要改:APP_ENV 生产写 production,APP_DEBUG 生产必须是 false(为 true 时错误页会把堆栈、环境变量、SQL 全部显示给访问者),APP_URL 写真实域名,影响签名链接和邮件里的地址。数据库相关的是 DB_CONNECTION=mysql、DB_HOST、DB_PORT、DB_DATABASE、DB_USERNAME、DB_PASSWORD。
404 与 500 的排查表
刚起步时遇到的错误,九成集中在这张表里。排查顺序按「请求有没有进 PHP」开始,能省掉大量无效猜测。
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 整站 404,应用日志为空 | Nginx root 指到了项目根目录,或缺少 try_files | nginx -T 看 root;看 access log 里是否由 Nginx 直接返回 |
首页正常,/api/health 404 | api 路由文件没生成,或 withRouting 没加 api | php artisan route:list --path=api |
| 500,日志写 Permission denied | storage/ 或 bootstrap/cache/ 对 FPM 用户不可写 | ls -ld storage bootstrap/cache 看属主和权限 |
| 500,提示缺少 encryption key | APP_KEY 为空或 .env 没被读到 | 看 .env 是否存在、APP_KEY 是否有值 |
| 500,Class not found | vendor 没装,或自动加载没生成 | composer install,再 composer dump-autoload |
| 502 Bad Gateway | PHP-FPM 没启动,或 socket 路径不对 | systemctl status php8.3-fpm,对 fastcgi_pass 的路径 |
| 浏览器直接下载 index.php | Nginx 没把 .php 交给 FPM | 看 location ~ \.php$ 是否存在、FPM 是否在监听 |
| 500 但页面只有 Server Error | APP_DEBUG=false,真实原因只在日志里 | tail -n 50 storage/logs/laravel.log |
| 命令行正常,网页报语法错误 | CLI 与 FPM 使用的 PHP 版本不同 | 分别执行 php -v 和看 FPM 池配置里的版本 |
这张表的用法是先看「应用日志有没有内容」。日志为空,问题在 PHP 之前,去查 Nginx 和 FPM;日志有内容,问题在框架内部,按异常类型查。顺序颠倒会让排查时间翻几倍。
边界与代价
这套「单机 Nginx + PHP-FPM + Laravel」的方案,到中等规模是够用的:一台 4 核 8G 的机器,跑一个普通业务 API,日请求百万级也能撑。真正开始吃力的信号通常不是 QPS,而是每次请求都要重新启动框架:加载配置、注册服务、解析路由,这些固定开销在请求变短、变多时占比越来越高。
继续往上走有两条路。一条是加机器、把会话和缓存外置到 Redis,让多台 FPM 共享状态;另一条是上 Laravel Octane,用常驻进程复用框架,减少启动开销。Octane 的代价很直接:常驻进程里单例和静态变量不会随请求清理,任何把请求数据存到单例、容器绑定或全局变量的代码都会串数据,而且这种 bug 在本地单进程下几乎复现不了。
框架选型本身也有代价。Laravel 的大版本节奏快,升级要跟;默认约定越多,隐式行为越多,排查时越依赖对框架的了解。真要把 Laravel 换成 Symfony,路由、控制器、ORM、认证、队列都要重写,业务逻辑可以搬,基础设施层基本是重做。所以选型要在项目早期定,不要写到一半再换。
还有一个不常被提起的成本:人对框架的熟悉度。一个团队如果没人真正读过框架的请求生命周期,出了问题只能靠搜索和试错,这时候框架带来的「快」会被排查时间吃掉。下一篇就把这条生命周期完整拆开。
另一个边界在状态存放。单机时把 session 写文件、把缓存写本地磁盘都很省事,一旦加第二台机器,同一个用户在两台机器上的登录态就不一致。这不是 Laravel 的问题,是「状态放在进程本地」这件事本身的代价。要跨机器,就得把 session、缓存、队列都外置到 Redis 或数据库,多了一层依赖,也多了一个可能故障的组件。第 4 篇会具体讲登录态放在哪一层。
当天能自己验证的练习
- 执行
composer create-project laravel/laravel demo "^12.0",进入目录后跑php artisan about,确认 PHP 版本、缓存驱动、数据库配置三项与预期一致。 - 故意把 Nginx 的
root改成项目根目录,重启后访问/api/health,观察 404 来自 Nginx 而不是 Laravel,并在 access log 里找到这条记录。 - 手动创建
routes/api.php并在bootstrap/app.php加api:参数,用php artisan route:list --path=api确认 URI 前缀是api/health。 - 把
.env里的APP_KEY清空,访问任意页面,记录报错原文;再执行php artisan key:generate,确认页面恢复。 - 分别用
php artisan serve和php -S 127.0.0.1:8000 -t public启动,对同一个接口发请求,对比两次的状态码差异并解释原因。
小结
三句话收束:入口只有 public/index.php,Nginx 的 root 和 try_files 决定请求能不能进框架;Laravel 12 没有 Kernel,路由和中间件都在 bootstrap/app.php 装配;.env 管环境、APP_KEY 管加密,两者都不能进仓库。
下一篇讲路由和中间件。这一篇只写了「一个接口能返回」,但真实项目里一个请求要经过全局中间件、路由分组、参数校验、异常处理才到你的代码。下一篇会把这条链路完整画出来,并解释为什么 CORS 预检会返回 404、为什么鉴权中间件放错位置会先于 JSON 解析执行。