在 Netlify 上构建与部署站点时：函数、Blobs…

当你需要在 Netlify 上编写 Serverless/Edge/Background/Scheduled 函数、使用 Netlify Blobs 存储、Image CDN 或配置 netlify.toml、环境变量与本地开发时使用。

适用场景

解决思路

1. 优先使用代码内导出的 `config` 对象进行配置，而不是 netlify.toml。
2. 导入 Netlify 包时绝不加版本号（用 `@netlify/functions`，不要用 `@netlify/functions@1.2.3`）。
3. 仅在明确需要时才添加 CORS 头。
4. 根据用例选择合适的函数类型：Serverless（标准 API，10s/Pro 26s 超时，路径 `/.netlify/functions/name`）、Edge（请求/响应修改，50ms CPU，自定义路径）、Background（长时异步任务，15 分钟，文件名带 `-background` 后缀）、Scheduled（Cron 任务，30s）。
5. 函数与 edge function 源码目录默认是 `netlify/functions` 和 `netlify/edge-functions`，可在 netlify.toml 中用 `[functions] directory` 和 `[build] edge_functions` 覆盖；netlify.toml 设置优先于 UI 构建配置。
6. Serverless 函数用 `export default async (request: Request, context: Context) => {}` 结构，校验请求方法、解析 body、处理业务逻辑、用 `Response.json` 返回，并用 try/catch 捕获错误返回 500。
7. 在 `export const config` 中配置 `path`（自定义路径会完全替换默认路径）、`method`（HTTP 方法数组）、`rateLimit`（如 `{ windowSize: 60, windowLimit: 100 }`）。
8. 利用 context 对象：`account`、`cookies`（get/set/delete）、`deploy`（context/id/published）、`geo`（city/country/latitude/longitude/subdivision/timezone/postalCode/ip）、`params`、`requestId`、`server.region`、`site`（id/name/url）。
9. 在运行时读写环境变量优先用全局 `Netlify.env.*`（get/has/set/delete/toObject），而不是 `process.env`。
10. Edge Functions 用于在请求到达源站前修改请求、返回前修改响应、基于地理位置的个性化、A/B 测试、边缘鉴权；用 `context.next()` 继续到源站，用 `Response.redirect` 重定向。
11. Edge Function 的 config 支持 `path`、`excludedPath`、`pattern`/`excludedPattern`（正则）、`method`、`onError`（'continue'|'fail'|'fallback'）、`cache: 'manual'`。
12. Edge Functions 运行在 Deno 上：可导入 Node 内置模块（`node:crypto`）、Deno URL 模块、npm 包（beta，含原生二进制或动态 require 的可能不可用）；可用 import maps，通过 netlify.toml 的 `[functions] deno_import_map` 声明。
13. Edge Functions 可用 Web API 有限：fetch/Request/Response/URL、TextEncoder/TextDecoder、Web Crypto、WebSocket、setTimeout/setInterval、Streams API、URLPattern。
14. 多个 Edge Function 匹配同一路径时，在 netlify.toml 中用 `[[edge_functions]]` 显式声明从上到下的顺序（缓存函数总是最后运行）；执行顺序为：配置函数 > 框架生成函数 > 用户内联函数，非缓存先于缓存，多个内联按文件名字母序；用 `context.next()` 继续链，不要用 fetch()/URL() 重新触发。
15. 注意 Edge Function 限制：20 MB 压缩代码、512 MB 内存、50ms CPU、40s 响应头超时；与 split testing、`_headers`/netlify.toml 自定义头、预渲染不兼容；只能重写到同站 URL；不包含在 HIPAA 合规托管中。
16. Background 函数：15 分钟墙钟超时、立即返回 202、返回值被忽略、文件名必须有 `-background` 后缀；长任务结果写入 Netlify Blobs 供后续查询。
17. Scheduled 函数：CRON 按 UTC 计算、最小间隔 1 分钟、30 秒执行限制、无响应体、请求体是含 `next_run` 的 JSON；只在已发布部署上运行（预览和分支部署不运行）；本地用 `netlify dev` 加 `netlify functions:invoke <name>` 测试；优先用代码内 `config.schedule`（如 `@hourly`、`@daily`、`@weekly`、`*/15 * * * *`、`0 9 * * 1-5`），也可在 netlify.toml 的 `[functions."name"] schedule` 中配置。
18. 优先用 Netlify Blobs 而非新建数据库，除非数据需要关系结构或搜索；限制：store 名 ≤64 字节、key ≤600 字节、单对象最大 5GB。
19. Blobs 默认最终一致（写入约 60 秒内传播），需要写后立即读时给 `getStore` 传 `{ consistency: 'strong' }`；无内置并发控制，最后写入获胜，需要时自行加锁。
20. 区分 deploy-specific store（`getDeployStore`，随部署同步、部署删除即移除，构建插件和文件上传必须用它）与 global store（`getStore`，跨分支持久、不自动清理）；写 global store 时用 `context.deploy.context === 'production'` 分支避免非生产数据泄漏。
21. Blobs 基本用法：`getStore('my-store')`、`store.set`/`setJSON`、`store.get`（可传 `{ type: 'json' }`）、`store.delete`、`store.list`；二进制数据用 arrayBuffer 存储并带 `metadata.contentType`，读取用 `{ type: 'blob' }`。
22. Image CDN 用法：`/.netlify/images?url=/images/hero.jpg&w=800&q=80`，参数包括 `url`（必填）、`w`、`h`、`q`（1-100）、`fit`（cover/contain/fill）、`fm`（webp/avif/auto）；可用 URLSearchParams 程序化生成。
23. 远程图片需在 netlify.toml 的 `[images] remote_images` 中允许域名（用绝对 URL），并对 `url` 参数做 URI 编码；可用 `[[redirects]]` 把友好路径映射到 `/.netlify/images`；自定义头只能用于同域图片且需明确要求；转换和源图在边缘缓存，新部署会使缓存失效。
24. 环境变量可通过 Netlify UI、CLI、API 或 netlify.toml 设置，优先级 netlify.toml > UI/CLI/API，站点专属变量优先于共享变量；CLI 需先 `netlify link`，命令包括 `netlify env:set`（可加 `--secret`）、`netlify env:unset`、`netlify env:import .env`、`netlify env:list --plain --context production`。
25. Netlify 构建不直接读 `.env` 文件，需用 `env:import` 导入；只有在确认 `.env.local` 已 gitignore 后才导出生产上下文，绝不提交。
26. 在 netlify.toml 中用 `[context.production.environment]`、`[context.deploy-preview.environment]` 等按部署上下文（production/deploy-preview/branch-deploy/dev/具体分支名）限定变量；敏感值不要写进 netlify.toml，用 UI 或 CLI。
27. 构建配置示例：`[build]` 中设 command/publish/functions，`[build.environment]` 设 NODE_VERSION，`[[redirects]]` 做 API 代理，`[[headers]]` 设安全头，`[functions] node_bundler = "esbuild"`，`[dev]` 设 command/port/targetPort。
28. 文件上传：在函数中用 `request.formData()` 取 File，写入 Blobs store，key 用 `${Date.now()}-${file.name}`，metadata 带 contentType 和 originalName。
29. 站点管理：检查 `.netlify/state.json` 是否有 `siteId` 判断是否已链接；`netlify init` 初始化新站点，`netlify link` 链接已有站点，`netlify deploy` 手动部署，`netlify deploy --prod` 部署到生产。
30. 本地开发：`netlify dev`（可加 `--port 8888`、`--live`）；`netlify functions:invoke hello --payload '{"name": "World"}'` 直接调用函数；`netlify functions:serve` 只启动函数服务。
31. 错误处理：定义结构化 ErrorResponse（error/code/details），用统一的 errorResponse 辅助函数返回；先校验输入（如缺 email 返回 400 MISSING_EMAIL），业务逻辑异常返回 500 INTERNAL_ERROR 并 console.error。
32. 安全：用 zod 等做输入校验（safeParse 失败返回 400 和 issues）；鉴权从 Authorization 头取 Bearer token 并验证 JWT，失败返回 401。
33. 避免常见陷阱：不给 @netlify/functions 加版本号、不无谓加 CORS 头、选对函数类型、background 函数记得 `-background` 后缀、background 函数用 Blobs 持久化、注意 15 分钟超时、校验输入、不硬编码环境变量、边缘函数妥善处理错误、别用 serverless 做更适合 edge 的任务、把 `.netlify` 加入 .gitignore、新站点未经要求不加 redirects/headers、非生产数据写入 deploy-specific 而非 global Blobs store。

适用边界 · 注意事项

• 不使用 Netlify 平台（其他托管/云厂商）时本经验不适用。
• 需要关系型数据库结构或全文搜索的数据不适合用 Netlify Blobs。
• Edge Functions 不适用于需要超过 50ms CPU、需要 HIPAA 合规托管、或依赖 split testing/自定义头/预渲染的场景。