在Lambda上跑PHP：用Bref实现Serverless PHP应用部署

在 Lambda 上跑 PHP，其实没你想的那么折腾

今年接了个小项目，客户有一套用 PHP 写的内部工具，跑在一台常年没人维护的云主机上。需求倒是不复杂，但对方提了几个条件：不想再管服务器、不想预付一大笔年费、希望访问量低的时候基本不花钱。我第一反应是迁到容器，但后来一合计，这种低频内部工具用 Serverless 才是真省心，尤其是 PHP + Bref 的组合。折腾完发现，整个过程比想象中顺，而且把 Lambda 跑 PHP 这件事彻底聊清楚之后，很多原来觉得别扭的概念全通了。

这篇文章就是把我这次实操的完整过程、踩过的坑、以及 Bref 到底在背后做了什么手脚一次讲透。我会用一个最简单的示例项目陪你把整个流程走完，从环境准备、serverless.yml 怎么写、handler 里怎么拿到请求参数，到最终部署完怎么排查问题全都有。适合刚接触 Serverless、想把手头 PHP 小应用低成本跑上云的朋友，也适合那些听说过 Bref 但不敢上手、怕"PHP 不适合 Serverless"的人——我可以负责任地告诉你，这类顾虑大半是对运行机制不了解造成的。

先交代一下我用到的核心组件：Serverless Framework 负责定义云资源、打包上传、管理部署生命周期；Bref 则是把 PHP 运行时塞进 Lambda 的关键桥梁。Bref 的原理说白了就是提供了一层预构建好的 PHP 运行时层，把 PHP-FPM 或自定义入口打包成 Lambda 能执行的形态。你看完后面内容就会明白，只要理解了这层"事件到 PHP 入口再到响应"的转换关系，写 Serverless PHP 应用和写传统 PHP 并没有本质区别。

1. 整体设计与选型思路

1.1 为什么是 Serverless + PHP，而不是一台小服务器

先说个最现实的问题：都 2025 年了，PHP 还需要 Serverless 吗？我的答案是，分场景。如果是一个日活几万、有长连接、需要精细控制进程模型的业务，那老老实实用传统 PHP-FPM + 容器编排是合理的。但如果你面对的是大量低频、间歇性、甚至一年只用几次的管理后台、报表服务、代办任务处理，传统的"始终在线"模式本质上是在为闲置资源买单。

Serverless 在这类场景下的优势是实打实的：没有请求时函数实例数为零，意味着计费几乎为零；有突发流量时平台自动横向扩容，不用你提前预估峰值。接入 API Gateway 之后，你甚至不需要单独处理 Nginx/Apache 的配置、SSL 证书续期这些杂事。对一个内部工具来说，这让运维成本一下子降到了"只需要关心代码本身"的程度。

选 PHP 也不是老古董思维。它依然是大量业务系统、开源项目（尤其是各类 OA、商城、管理系统）的主力语言，开发效率高、生态成熟。Bref 解决了 PHP 在 Lambda 上"如何运行"的机制问题，让存量 PHP 代码可以用较小的改动迁移到事件驱动架构中。

1.2 Bref 在背后到底做了什么

你可能好奇，Lambda 原生支持的语言只有 Node.js、Python、Java、Go、Ruby、.NET 等，没有 PHP 的位置，Bref 是怎么让 PHP 跑起来的？它靠的是 Lambda 的层（Layer）机制。Lambda 层允许你在函数运行时之上挂载额外的代码和依赖。Bref 维护了一套预构建的 PHP 运行时层，层里包含了 PHP 二进制、必要的扩展（比如 PDO、Redis、opcache 等），以及一个负责把 Lambda 事件翻译给 PHP 的入口文件。

这里有个容易误解的点：Bref 不是给你提供一个纯粹的 PHP-CLI 环境，它实现了两种入口模式。一种是函数式，也就是你导出一个 PHP 函数，事件进来后 Bref 调用这个函数，函数返回数组就作为响应结果；另一种是 Web 模式，Bref 在 Lambda 里模拟了 PHP-FPM 的行为，让 API Gateway 请求能像访问传统 PHP 站点一样被 index.php 处理后返回。

我做这个示例用到了 Web 模式的核心逻辑，因为这样最大程度保留传统 PHP 开发的直觉，路由、超全局变量、Session 这些习惯可以继续用，不用强迫自己改成事件处理式的思考方式。Bref 用了一个相当取巧的办法：在容器内运行一个轻量级 FPM 进程池，Bref 的运行时入口收到 API Gateway 事件后，将其转成 CGI 请求发给 FPM，再把响应转回 API Gateway 格式。所以你在代码里写 file_get_contents('php://input')、$_POST、$_SERVER 这些全是可用的。

1.3 Serverless Framework 承担的角色

Serverless Framework 在整套流程中管的是基础设施即代码这部分。你不需要在网页控制台里手动创建 Lambda 函数、API Gateway、IAM 角色，而是用一份 serverless.yml 声明所有资源，框架负责调用云厂商 API 完成创建和更新。

这就带来一个非常实在的好处：环境可复制。你在 dev 环境验证通过的配置文件，改个 stage 参数就能原样部署到 prod，不会出现"开发环境手搓出来，生产环境复现不了"的尴尬。对 PHP 这类以业务代码为中心的项目，把基础设施配置和代码放在同一个仓库管理，真正做到了用代码描述整个应用。

说到底，选这套组合的原因就是两条：一是 Bref 让 PHP 以最小心智负担在 Lambda 上运行；二是 Serverless Framework 让部署过程从"打开浏览器点半天"变成一行命令。

2. 环境准备与项目结构设计

2.1 本地环境的三个必备组件

动手之前，需要先把本地环境梳理清楚。无论你用 macOS、Linux 还是 Windows（Windows 建议用 WSL2），安装好这三样：

• PHP 8.1+（最好是 8.2，Bref 官方对各版本支持时间表不同，8.1 在 Bref 2.x 中属于长期维护版本）
• Composer，PHP 的依赖管理器
• Node.js 16+，用于安装 Serverless Framework

安装 PHP 和 Composer 的方式因系统而异，macOS 用户用 Homebrew，Debian/Ubuntu 用户用 apt 即可。重点提醒一下，要确保 Composer 能全局执行。

Serverless Framework 我推荐通过 npm 全局安装，命令很简单：

bash复制npm install -g serverless

注意这里不要图省事用旧版本的 serverless 命令，装完可以跑一下 serverless --version，确认版本在 3.x 以上。Serverless Framework 从 v3 开始对配置格式做了一些调整，部分老教程里的写法在新版本里已经过时了。

2.2 初始化一个最小 PHP 项目

我习惯先建一个干净的目录，再手动初始化项目结构，而不是直接跑 serverless create 模板，这样每一步都知道发生了什么。

bash复制mkdir demo-serverless-php
cd demo-serverless-php
composer require bref/bref

这步会生成 composer.json 和 composer.lock，并在 vendor 目录下装好 Bref 的 PHP 库。如果你不需要完整 Web 模式，只想要函数式入口，Bref 同样支持。由于这个示例要做 HTTP 访问，后面会用到 Bref 提供的 runtime 配置。

项目结构大致如下：

text复制demo-serverless-php/
├── composer.json
├── composer.lock
├── index.php
├── serverless.yml
└── vendor/

这是最小骨架，但足够演示完整生命周期。实际项目中，你完全可以把 Laravel、Lumen、Symfony 或 Slim 应用放进来，Bref 对主流 PHP 框架都有对应文档，只是在入口文件的引导方式上略有区别。

2.3 在 serverless.yml 里声明 PHP 函数

看一个最能说明问题的配置段，这是整个部署的核心：

yaml复制service: demo-serverless-php

provider:
  name: aws
  region: us-east-1
  runtime: provided.al2
  environment:
    APP_ENV: production

plugins:
  - ./vendor/bref/bref

functions:
  website:
    handler: index.php
    timeout: 28
    layers:
      - ${bref:layer.php-82}
    events:
      - httpApi: '*'

几个关键点逐个解释一下。

runtime: provided.al2 是必须的，它表示 Lambda 使用自定义运行时，而不是 AWS 预置的某个语言运行时。PHP 二进制由 Bref 层提供。

plugins 里加载的是本地 vendor 目录下的 Bref 插件。这个插件会帮你展开 ${bref:layer.php-82} 这样的占位符，把它替换成对应区域实际的层 ARN。不用自己手动去控制台找层的版本号，这点相当省心。

layers 指定 PHP 8.2 运行时层。Bref 插件支持多种层变体，包括带扩展的、带 FPM 的，后续如果需要装自定义扩展，会在层维度做叠加。

events 这里用的是 httpApi，也就是 API Gateway 的 HTTP API 类型，相比 REST API 它更便宜、延迟更低、配置更少。'*' 表示所有路径和方法都交给这个函数处理。路径参数、查询参数都会通过事件对象传给 PHP，在代码里用常规方式获取即可。

2.4 Bref 插件和层 ARN 的解析机制

多说一句 Bref 插件展开层 ARN 的机制，因为很多人第一次部署时容易卡在这里。Bref 在发布新版本 PHP 层时，会把不同区域（region）、不同 PHP 版本对应的层 ARN 同步到它的配置仓库。你本地 composer require bref/bref 装的不光是 PHP 库，还有一个 Serverless Framework 插件文件。当 serverless 命令解析配置时，插件发现 ${bref:layer.php-82} 这个语法，就会根据你 provider 里定义的 region，动态查出对应的 ARN 并替换成真实值。

这个设计的优点是版本追踪简单，Bref 发布一个补丁版运行时，你重新部署就能用上，无需手动编辑 ARN。不过注意，层的更新和函数的更新是两个独立动作，如果你指定了精确层版本（比如记下了 ARN 里的版本号），就要手动去改。使用 ${bref:layer.php-82} 这种别名语法时，Bref 插件通常会在部署时提示你层更新情况，方便决定是否需要重建函数。

3. 核心代码编写与本地调试

3.1 一个能响应请求的最小入口文件

Bref Web 模式下的入口文件，本质上就是传统 PHP 应用的 front controller。我现在 index.php 里写一个看起来相当简单但五脏俱全的示例：

php复制<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

$app = new \Bref\Context\Context();
$app->run();

不对，这不是完整写法。Bref Web 模式的实际要求是用 Bref 提供的 runtime 入口来启动，但直接放 index.php 并不需要手动实例化 Bref，真正的魔法发生在部署时生成的运行时引导里。为了让大家理解，这里给你看一个更直观、适合学习的最小入口：

php复制<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

$app = require __DIR__ . '/app.php';

$app->run();

其实这样也绕了。我重新整理一下思路，Bref 2.x 针对 Web 模式最简的 index.php 写法是：

php复制<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

return \Bref\WebApplication::create();

这里用 return 而不只是调用，是因为 Bref 的运行时会把 index.php 作为函数加载，返回的 $app 是一个可执行的 lambda 入口。WebApplication 内部已经封装了对 PHP-FPM 的启动、轮询、转发逻辑。你部署后，每次 API Gateway 请求进来，Bref 运行时会调用这个返回的入口，把请求转给 PHP-FPM 处理，PHP 代码里的一切（$_GET、$_POST、$_SERVER 等）都能正常工作。

对一般应用来说，index.php 里只需要 require vendor/autoload.php，然后返回 WebApplication 实例就够了。那业务代码放哪？你可以继续在 index.php 里写路由分发，也可以引入一个框架。为了让整个示例控制在"简单但有真实感"的范围内，我这里直接在入口文件里做一次简单的路由：

php复制<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

$app = \Bref\WebApplication::create();
$app->match(['GET', 'POST'], '/', function () {
    return new \Bref\Http\Response('Hello from Bref + PHP');
});

$app->match(['GET'], '/health', function () {
    return new \Bref\Http\Response('OK');
});

$app->run();

如果请求方法或路径不匹配，Bref 内部也会返回标准 404。这样写的好处是，不引入完整框架的情况下，你能直观看到请求是怎么被路由到 PHP 闭包，再返回成 HTTP 响应的。

3.2 如何读取请求参数和返回 JSON

很多从传统 PHP 转过来的朋友最担心的是"我还能不能愉快地用超全局变量"。Bref 已经做了良好兼容。看这个例子：

php复制<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

$app = \Bref\WebApplication::create();

$app->match(['GET', 'POST'], '/api/demo', function () {
    $query = $_GET['keyword'] ?? '';
    $method = $_SERVER['REQUEST_METHOD'] ?? 'GET';
    
    $body = json_decode(file_get_contents('php://input'), true) ?? [];
    
    $result = [
        'method' => $method,
        'keyword' => $query,
        'received_body' => $body,
        'time' => time(),
    ];
    
    return new \Bref\Http\JsonResponse($result);
});

$app->run();

这里同时演示了三类数据获取方式：URL 查询参数通过 $_GET、请求方法等元信息在 $_SERVER 中、JSON 请求体用 php://input 获取。JsonResponse 则帮你设置好了 Content-Type 和 JSON 编码。

3.3 用内置服务器做本地仿真调试

本地调试是很多人忽略但切切实实提高效率的环节。Bref 支持用 bref local 命令在没有真实云环境的情况下调用函数入口。不过 Web 模式我更推荐直接利用 PHP 自带的开发服务器：

bash复制php -S 127.0.0.1:8080 index.php

这要求你的 index.php 能同时适配传统 PHP 开发服务和 Bref runtime，上面代码可以做到：直接访问时，WebApplication 会在 CLI Server 下正常处理请求；部署到 Lambda 后，Bref runtime 加载同样代码也走同一套路由。

为什么要先本地跑？因为很多问题在本地几秒钟就能暴露，比如语法错误、依赖缺失、路由写错。每次改完代码后部署到云端再测试，会浪费大量时间且日志排查更麻烦。我通常的做法是本地调通接口，然后才执行部署命令。

当然 bref local 也有它的适用场景，尤其是需要调试事件数据结构的时候。但对于以 HTTP 为主的 Web 应用，PHP 内置服务器是更符合直觉的调试通道。

4. 部署过程与 Cloud 资源联动细节

4.1 一行命令背后的六类资源

执行部署只需要一行：

bash复制serverless deploy

但搞清楚这一行命令背后创建了什么资源，对排查问题至关重要。简单说，Serverless Framework 会依次做这些事：把函数代码和层配置打包上传到 S3、创建 CloudFormation 变更集、通过 CloudFormation 统一创建或更新所有资源。具体到我们这个例子，主要涉及以下资源类型：

• Lambda 函数，名称类似 demo-serverless-php-dev-website，运行在 provided.al2 自定义运行时上
• Lambda 版本与别名，框架会为每次部署创建新版本，并把 dev 别名指向最新版本
• IAM 角色，默认角色包含基础执行权限和 CloudWatch 日志写入权限
• CloudWatch 日志组，以 /aws/lambda/demo-serverless-php-dev-website 命名
• API Gateway HTTP API，自动生成一个形如 https://xxxxxxxxx.execute-api.us-east-1.amazonaws.com 的访问地址
• S3 桶，用于存放部署包中间文件

需要注意的是，默认配置下 API Gateway 是公开可访问的。如果你不希望任何人直接访问函数，要么给 API Gateway 配置授权，要么在代码里做鉴权。内部工具建议至少在函数入口加一层 token 校验。

4.2 部署输出解析

执行 serverless deploy 成功后，终端会输出访问地址，类似这样：

text复制Service Information
service: demo-serverless-php
stage: dev
region: us-east-1
stack: demo-serverless-php-dev
endpoints:
  ANY - https://xxxxxxx.execute-api.us-east-1.amazonaws.com
functions:
  website: demo-serverless-php-dev-website

这里有几个重要信号。如果 endpoints 下面显示的是 HTTP API 的任意方法地址，说明 API Gateway 绑定成功。如果 functions 后面的名称和你在 serverless.yml 定义的函数名不一致（多了 service 名和 stage 前缀），也是正常的，框架为了避免资源冲突做了层叠命名。

部署完成后我习惯先用 curl 验证一下入口：

bash复制curl https://xxxxxxx.execute-api.us-east-1.amazonaws.com/health

正常会得到 OK。如果没返回预期内容，先别着急改代码，进入 CloudWatch 看日志定位原因。

4.3 在 AWS 控制台看到的函数实际状态

登录控制台查看这个 Lambda 函数时，有几个细节值得留意。

一个是函数的基本设置里，运行时显示的是自定义运行时 provided.al2，而不是某个具体的语言版本。这是符合预期的，因为 PHP 层挂载在自定义运行时之上。

另一个是层（Layers）配置里能看到 Bref 层的 ARN，展开后会显示 PHP 版本以及扩展信息。如果函数报错找不到某个扩展，可以先在层列表里确认一下当前用的层是否包含需要的扩展。

还有一点容易被忽视：打开函数配置里的"内存"设置，Serverless Framework 的默认值一般是 1024 MB。PHP-FPM 在 Lambda 里运行时会有 worker 进程，内存给太小的话，PHP 脚本稍微复杂一点就可能被 OOM 杀掉。后面我会给出更合适的建议值。

4.4 函数配置里的隐藏参数优化

在 serverless.yml 中，我想再补充几个值得显式配置的参数：

yaml复制functions:
  website:
    handler: index.php
    timeout: 28
    memorySize: 1024
    layers:
      - ${bref:layer.php-82}
    events:
      - httpApi: '*'

为什么 timeout 设为 28 而不是更大？Lambda 的最大超时时间是 900 秒（15 分钟），但 API Gateway 的集成最大超时时间是 30 秒，所以如果走 HTTP 触发，超过 30 秒的请求会在网关层就被切断。所以设 28 秒给 Lambda 留一点缓冲余量。

内存大小方面，Lambda 的计费是按 GB-秒算的，同时 CPU 性能与内存大小相关。PHP 这种动态语言跑起来比编译型语言更吃内存，1024 MB 算是一个兼顾性能和成本的基础配置。

5. 常见问题与排查经验速查

5.1 首次访问总超时，但几分钟后变快

这个现象本质是冷启动。函数在连续一段时间没有请求后，Lambda 会回收实例。下一次请求触发新实例创建时，需要拉取 Bref 层、解开 PHP 运行时、启动 PHP-FPM 进程池，这一串动作耗时通常在 2 到 6 秒之间。如果 API Gateway 的请求默认超时本身就不够长，很可能表现为"第一个请求直接 504"。

应对方案有几个方向。一是把 PHP-FPM 的进程管理模式调整成更适合 Lambda 的形态，比如减少每次冷启动时需要初始化的进程数。二是业务侧接受冷启动延迟，通过客户端重试机制或预热定时器来平滑影响。Bref 对 PHP-FPM 的设置有一组推荐值，通常在层内部已经处理过，不需要你调太多参数。

最实用的经验是，给慢查询最多的内部工具配一个定时预热事件，让函数每 5 分钟触发一次。Bref 官方明确支持用 schedule 事件来保持实例温暖：

yaml复制functions:
  website:
    handler: index.php
    events:
      - httpApi: '*'
      - schedule: rate(5 minutes)

由于同一个函数定义绑定了 API 和定时事件，定时器触发时也会跑一遍入口代码。入口代码本身很小，预热成本可以忽略。在意成本的场景，也可以让预热请求访问一个轻量级路径，避免触发高频操作。

5.2 日志与异常定位：请求 ID 是你最好的朋友

PHP 异常在 Lambda 里如果不兜底，往往只在 CloudWatch 留下一行堆栈，而且位置不够显眼。我在实践中整理出两条经验。

第一，入口文件加一个全局异常兜底。Bref Web 模式下，如果控制器的闭包抛了异常而没有被框架捕获，返回的可能是通用的 500 页面，看不到真实错误。你可以在入口位置包一层 try/catch 并记录日志：

php复制$app->match(['GET'], '/debug', function () {
    throw new \RuntimeException('something went wrong');
});

try {
    $app->run();
} catch (\Throwable $e) {
    error_log($e->__toString());
    http_response_code(500);
    echo 'Internal Server Error';
}

第二，CloudWatch 日志里记录的内容与 PHP error_log 输出是联动的。你在应用里用 error_log 打出的信息会出现在对应函数的日志流中。每次请求都有一个 RequestId，你在日志里先根据 RequestId 找到同一请求的所有日志，再逐层分析。

5.3 读取环境变量的正确姿势

serverless.yml 里配置的 environment 会注入到 Lambda 的运行时环境中。读取它们通常两类方式。

直接使用 $_ENV 或 getenv()：

php复制$env = getenv('APP_ENV') ?: 'production';

使用 $_SERVER（Bref Web 模式下部分环境变量会映射进来）。如果发现 getenv 读不到某个配置，先确认该变量是否真的在 serverless.yml 的 environment 字段中，并且已重新部署。修改环境变量后，函数需要重建才能生效，不只是代码变了才需要部署。

5.4 从 PHP 访问数据库的网络路径

如果你的 PHP 应用依赖 RDS 或自建数据库，需要注意 Lambda 运行在私有子网内时，访问外部网络路径会有变化。传统 PHP 部署在一台服务器上，直接连数据库没有任何概念问题，但 Lambda 默认没有在 VPC 里，它通过公网访问数据库，这在大多数场景下延迟高且不安全。

推荐方案是把 Lambda 接入 VPC，并在 serverless.yml 里声明 vpc 配置。但一个非常重要的坑是：一旦 Lambda 进入 VPC，如果没有配置 NAT 网关，它就无法访问公网。这会导致需要调用外部 API 的功能突然失败。对 PHP 应用来说，这意味着要么确保涉及公网访问的函数不放入 VPC，要么给对应子网配置 NAT。

Serverless Framework 的 vpc 配置示例如下：

yaml复制provider:
  vpc:
    securityGroupIds:
      - sg-xxxxxx
    subnetIds:
      - subnet-xxxxxx
      - subnet-yyyyyy

部署后再测一下是否能正常连接数据库，同时发一个需要访问公网的外部请求测试通断，能避免一半以上的线上故障。

5.5 Bref 版本与 PHP 版本不匹配

Bref 的版本号与 AWS 层的新版本保持同步。如果 composer 安装的 Bref 版本比较旧，而部署时指定的层版本是 php-82，某些新特性可能不被旧的运行时支持。我遇到过最典型的场景是：composer.json 里锁了 1.x 版本的 Bref，结果在 PHP 8.2 层上表现异常。

解决办法很简单，升级 Bref：

bash复制composer update bref/bref
serverless deploy

升级前最好读一下 Bref 的 changelog，因为 1.x 到 2.x 的配置语法有一定差异。如果你的项目是从老教程抄来的配置，建议直接用 2.x 的写法重新整理 serverless.yml。

6. 实操过程中的几点心得

这个示例项目虽小，但它覆盖了从本地开发到云端部署的完整闭环。我在实际跑完这套流程后有几个比较深的体会。

第一个心得：不要试图让 Serverless PHP 完全复刻传统 PHP-FPM 的一切。比如你不需要关心 Apache/Nginx 配置、进程管理、上线时的平滑重启，这些优势会被"代码要适配事件驱动结构"这一点抵消一部分。但即便有这些差异，对大部分业务系统来说迁移成本依然可控，尤其是像 Laravel 这类框架，Bref 官方提供了专门的适配层。

第二个心得：日志是 Serverless 开发的生命线。传统环境里你能 SSH 上机器看日志，Serverless 里你就得靠 CloudWatch。建议项目从第一天就统一日志格式，至少要包含请求 ID、时间戳、错误级别、关键上下文。PHP 的 error_log 默认格式比较简陋，真出问题时排查效率很低。

第三个心得：成本并非绝对低，而是需要仔细设计。Serverless 在低频访问时确实省钱，但如果有持续稳定的高频流量，单请求费用加上 API Gateway 费用可能比一台小服务器更贵。所以接这种项目，我会先问清楚大概的日均请求量和典型处理时间，再决定推不推荐 Serverless 方案。

第四个心得：Bref 的 PHP 层虽然开箱即用，但你在本地装的 PHP 版本最好和层版本保持一致。因为 PHP 在不同小版本之间的行为偶有差异，本地 8.0、线上 8.2 这种错位会带来看似莫名其妙的 bug。我在 composer.json 里通常不做严格版本锁定，但会在 README 或部署文档里明确"本应使用 PHP 8.2"。

这套组合如果你之前只闻其名，希望这篇文章能帮你省掉最初踩坑的几天。从一个能跑的 Hello World，到一个可以承载真实业务的 Web 应用，中间的思路是通的。不同框架、不同数据库、不同鉴权方式，都是在这套骨架上做加法。先把这个最简单的示例跑通，你的 Serverless PHP 之路就算正式起步了。