面向中文开发者的 AWS 实战知识库 代维服务
上云咨询

Lambda@Edge(Lambda@Edge)服务指南:入门 · 配置 · 排错 · 代运维 · 部署

快速信息

它是什么

Lambda@Edge 是 Lambda 的一种部署形态:函数不在你指定的某个区域长期驻留,而是随 CloudFront 的分发配置被复制到边缘站点,在 HTTP 请求/响应的生命周期里被触发执行。它在架构中的位置固定在 CloudFront 的缓存行为(cache behavior)上——你为某条 path pattern 绑定一个已发布版本的函数 ARN,CloudFront 在转发请求或返回内容的过程中调用它。

与普通 Lambda 的边界需要先划清:函数本身在 us-east-1 创建和管理,执行却发生在离用户或源站更近的站点。因此它没有 VPC、没有环境变量、没有 Layer,也不支持预置并发,这些在普通 Lambda 上习以为常的能力在这里都不可用。与 CloudFront Functions 的边界是:CloudFront Functions 只处理 viewer request/response 上的轻量 JavaScript 逻辑,执行时间远短;Lambda@Edge 支持 Node.js 与 Python,可访问外网、执行时间更长,并且能挂到 origin 侧。

相对于在源站(ALB、EC2、API Gateway)做同样的事,Lambda@Edge 的价值是把判断提前到离用户最近的地方:请求不必回到源站就被改写、拦截或直接应答,源站压力和回源延迟都随之下降。

触发事件 触发时机 典型用途
viewer request 收到用户请求、查询缓存之前,每个请求都执行 鉴权、重定向、改写 URI 与 header
viewer response 返回给用户之前,包含缓存命中的响应 注入安全响应头、Cookie 处理
origin request 缓存未命中、转发给源站之前 选择源站、拼装回源路径、加源站鉴权 header
origin response 收到源站响应、写入缓存之前 改写响应头、按状态码调整返回结果

核心概念

  • 触发事件(event type):函数挂载在 CloudFront 请求生命周期的四个位置之一,位置决定它能读到什么、能改什么,也决定调用量。
  • event 对象:形如 event.Records[0].cf.request 或 event.Records[0].cf.response,包含 method、uri、headers、querystring、clientIp 等字段。
  • 关联(association):把「已发布版本的函数 ARN + 事件类型」绑定到某条 cache behavior,这是让函数上线的唯一途径。
  • 版本与复制:CloudFront 只接受带数字版本号的 ARN,不接受 $LATEST;版本会被复制到各边缘站点,变更生效不是即时的。
  • 响应结构:函数必须返回结构合法的 request/response 对象(status、headers、body 等),字段不合法或修改了只读字段会被拒绝。

典型场景

  • 边缘鉴权:在 viewer request 校验 JWT 或签名 Cookie,非法请求直接在边缘返回 401,不消耗源站资源。
  • A/B 测试与灰度:在 viewer request 按 Cookie 或比例改写回源路径与来源,把分流逻辑从应用层挪到边缘。
  • 统一安全响应头:在 viewer response 注入 HSTS、CSP 等 header,一次覆盖静态与动态全部内容。
  • 多源站与回源改写:在 origin request 按用户地理、设备或路径动态选择 origin、拼装回源路径、附加源站鉴权 header,避免维护多套分发。

计费与成本要点

  • 两个维度:请求数(按触发次数)与计算时间(按内存 × 执行时长换算的 GB-秒),这部分与 CloudFront 的流量、请求费用分开计算。
  • 触发位置决定调用量:viewer 侧函数对每个请求都执行(含缓存命中),origin 侧函数只在回源时执行,后者的调用量通常低得多。
  • 优先评估 CloudFront Functions:纯 header/URL 改写、简单重定向用它更划算;只有需要外网访问、更长执行时间或 origin 侧触发时才上 Lambda@Edge。
  • 压缩执行时间与内存配置:精简依赖、避免在 viewer 侧做同步外部调用,缩短时长即直接减少 GB-秒。

上手步骤

  1. 在 us-east-1 创建 IAM 执行角色,信任 lambda.amazonaws.com 并授予写 CloudWatch Logs 的权限;在 IAM 控制台的角色详情页确认信任策略与权限已生效。
  2. 在 us-east-1 创建函数,选择 Node.js 或 Python 运行时,handler 读取 event.Records[0].cf.request。用控制台的 CloudFront 事件测试模板触发一次,确认返回对象结构正确。
  3. 发布版本:aws lambda publish-version --function-name <name>,记下输出中带版本号的 ARN;用 aws lambda list-versions-by-function 确认该版本已存在。
  4. 在 CloudFront 控制台编辑目标 distribution 的 Behaviors,为对应 cache behavior 添加 Function association,选择事件类型并填入 Lambda@Edge 的版本 ARN 后保存;验证方式是该 behavior 详情中已显示这条关联。
  5. 等待 distribution 状态回到 Deployed 后,用 curl -I 请求相应路径,检查被改写的 header、重定向或状态码是否符合预期。
  6. 打开 CloudWatch Logs,在函数副本实际执行的区域找到 /aws/lambda/us-east-1.<function-name> 日志组,确认有调用记录与预期输出。

常见问题与排查

症状:更新代码后线上行为没有变化

原因:Lambda@Edge 只认已发布版本,$LATEST 不会生效;同时已部署的副本需要时间复制和被替换。

处理:重新发布版本,把 CloudFront 关联的 ARN 换成新的版本号;等 distribution 状态恢复 Deployed 后再验证,避免在复制过程中反复改动。

症状:CloudFront 返回 5xx,或报 Lambda validation error

原因:函数返回的 request/response 对象结构不合法,修改了不可修改的字段,或 viewer 侧函数执行超时(viewer 侧的时长与包体积上限明显小于 origin 侧)。

处理:用 CloudFront 事件模板在控制台复现,逐一核对 status/headers/body 结构;在函数内做异常兜底,出错时返回原始 request;精简 viewer 侧逻辑与依赖。

症状:配置时无法添加环境变量、VPC 或 Layer

原因:这些能力 Lambda@Edge 本身不支持,且函数与执行角色必须在 us-east-1 创建。

处理:把配置打包进部署包或改为运行时从外部获取,去掉 VPC 依赖;确认函数与角色都位于 us-east-1。

症状:找不到函数日志

原因:日志写在使用该函数副本的区域,而不是 us-east-1;日志组名为 /aws/lambda/us-east-1.<函数名>。

处理:在 CloudWatch Logs 中按该日志组名跨区域查找,并确认执行角色具备写日志权限。

最佳实践

  • 按事件位置选型:能放到 origin request/response 的逻辑不要放在 viewer 侧,既减少执行次数,也避开最严格的超时与包体积限制。</li