§12 缓存与 edgeone.json：把性能和规则配出来

12.1 浏览器缓存与边缘缓存是两件事

3 天前我帮人调一个"更新了但用户看不到新页面"的 bug。根因是他把浏览器缓存和边缘缓存混为一谈。

浏览器缓存：存在用户浏览器里。Makers 对带哈希的文件（如 main.a1b2c3.js）给 max-age=31536000（一年）长期缓存；对 index.html 给 max-age=0，保证新鲜。
边缘缓存：存在 EdgeOne 节点上，静态资源首次请求后缓存，最长三个月。每次新部署自动失效。

重点看

边缘缓存"新部署自动失效"这件事，意味着你不用手动清缓存。改完推上去，用户自然拿到新的。

12.2 默认规则够用，但你要懂

大部分项目用默认就够。但当你要改响应头、做重定向、自定义构建，就得上 edgeone.json——放在项目根目录，覆盖控制台的项目设置。

12.3 用 edgeone.json 改缓存与加安全头

{
  "headers": [
    {
      "source": "/*",
      "headers": [
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Cache-Control", "value": "max-age=7200" }
      ]
    },
    {
      "source": "/assets/*",
      "headers": [
        { "key": "Cache-Control", "value": "max-age=31536000" }
      ]
    }
  ]
}

标叔的提醒：headers 最多 30 条；key 限 1-100 字符、value 限 1-1000 字符且不支持中文。我见过有人把中文塞进 value，部署直接挂。

12.4 重定向与重写：redirects / rewrites

{
  "redirects": [
    { "source": "/articles/:id", "destination": "/news-articles/:id", "statusCode": 301 },
    { "source": "/old-path", "destination": "/new-path", "statusCode": 302 }
  ],
  "rewrites": [
    { "source": "/assets/*", "destination": "/assets-new/:splat" }
  ]
}

能力	行为	数量上限	标叔的结论
redirect	换 URL（301/302）	100 条	改路径用它
rewrite	内部改写，URL 不变	100 条	静态资源迁移用它
两者 source 长度	≤500 字符	-	别写超长

警告：rewrites 只适用于静态资源，不支持 SPA 前端路由重写。SPA 的重写得用框架自己的路由系统，别在 edgeone.json 里硬配。

12.5 自定义构建：buildCommand / nodeVersion

{
  "buildCommand": "next build",
  "installCommand": "npm install",
  "outputDirectory": "./build",
  "nodeVersion": "22.11.0"
}

标叔的建议：nodeVersion 只认预装版本（14.21.3 / 16.20.2 / 18.20.4 / 20.18.0 / 22.11.0）。填别的号，部署直接失败。这坑我替你记着。

12.6 配置即代码，别只在控制台点

上面这些，控制台都能点。但写在 edgeone.json 里，它随仓库版本走，回滚跟着代码回滚。

下一章，我们用 CLI 把这些"点出来的配置"变成"敲出来的命令"。