项目是这么起的:执行 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,照抄会找不到文件。

本机已装 PHP 8.3.36 CLI(NTS x64)与 Composer 2.11.1,并用 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 12Symfony 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 CLI8.3跑 artisan、Composer、队列命令行直接找不到 php
PHP-FPM8.3给 Nginx 提供 PHP 进程502 Bad Gateway
扩展pdo_mysql、mbstring、openssl、tokenizer、xml、ctype、json、bcmath、fileinfo、curl数据库、字符串、加密、框架启动启动时报缺少扩展或类
Composer2.x安装依赖、生成自动加载无法 create-project
MySQL8.0业务数据连接被拒或驱动不存在
Redis7.x(可选)缓存与队列可先用 database 驱动顶上
Nginx1.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 里三个键齐全,就说明从内置服务器到路由再到响应这条链路是通的。

三种启动方式,别用错场景

同一个项目有三种跑法,用途完全不同。混用是很多「本地正常、线上异常」的起点。

php artisan serve开发用。它启动 PHP 内置服务器并挂了一个路由脚本,所有请求都进 public/index.php。单进程,改代码即生效,不要用于压测,也不要用于生产。
php -SPHP 自带的内置服务器。只写 -t public 时,它只把存在的文件当静态文件返回,/api/health 这种不存在的路径会直接 404。要让它转发,必须把入口脚本作为路由脚本传进去。
Nginx + PHP-FPM生产用。Nginx 负责连接、静态文件、超时和限流,PHP-FPM 负责执行。请求是否进框架,取决于 Nginx 的 root 和 try_files 配置。

第二种的正确写法是:

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_filesnginx -T 看 root;看 access log 里是否由 Nginx 直接返回
首页正常,/api/health 404api 路由文件没生成,或 withRouting 没加 apiphp artisan route:list --path=api
500,日志写 Permission deniedstorage/ 或 bootstrap/cache/ 对 FPM 用户不可写ls -ld storage bootstrap/cache 看属主和权限
500,提示缺少 encryption keyAPP_KEY 为空或 .env 没被读到看 .env 是否存在、APP_KEY 是否有值
500,Class not foundvendor 没装,或自动加载没生成composer install,再 composer dump-autoload
502 Bad GatewayPHP-FPM 没启动,或 socket 路径不对systemctl status php8.3-fpm,对 fastcgi_pass 的路径
浏览器直接下载 index.phpNginx 没把 .php 交给 FPM看 location ~ \.php$ 是否存在、FPM 是否在监听
500 但页面只有 Server ErrorAPP_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 篇会具体讲登录态放在哪一层。

当天能自己验证的练习

  1. 执行 composer create-project laravel/laravel demo "^12.0",进入目录后跑 php artisan about,确认 PHP 版本、缓存驱动、数据库配置三项与预期一致。
  2. 故意把 Nginx 的 root 改成项目根目录,重启后访问 /api/health,观察 404 来自 Nginx 而不是 Laravel,并在 access log 里找到这条记录。
  3. 手动创建 routes/api.php 并在 bootstrap/app.php 加 api: 参数,用 php artisan route:list --path=api 确认 URI 前缀是 api/health。
  4. 把 .env 里的 APP_KEY 清空,访问任意页面,记录报错原文;再执行 php artisan key:generate,确认页面恢复。
  5. 分别用 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 解析执行。