边缘安全加速平台 EO edgeone.json

配置文件包括以下设置项：

一、buildCommand

覆盖 控制台 > Makers 项目 > 项目设置 > 构建部署配置 中的构建命令。

{ "buildCommand": "next build"}

二、installCommand

覆盖 控制台 > Makers 项目 > 项目设置 > 构建部署配置 中的安装命令。此配置项可自定义构建过程使用的 包管理器。

{ "installCommand": "npm install"}

三、outputDirectory

覆盖 控制台 > Makers 项目 > 项目设置 > 构建部署配置 中的输出目录。

{ "outputDirectory": "./build"}

四、nodeVersion

指定构建环境的 Node 版本。建议使用系统预装的 14.21.3、16.20.2、18.20.4、20.18.0、22.11.0 几个版本，若填写其他版本号，可能导致部署失败。

{ "nodeVersion": "22.11.0"}

五、redirects

将请求从一个 URL 重定向到另一个 URL，以下是几个重定向的示例。

使用 301 永久重定向将请求从 /articles/+ ID 的 URL（例如 /articles/123），重定向到 /news-articles/ + ID 的 URL（例如 /news-articles/123）：

{ "redirects": [ { "source": "/articles/:id", "destination": "/news-articles/:id", "statusCode": 301 } ]}

使用 302 临时重定向将请求从 /old-path ，重定向到 /new-path ：

{ "redirects": [ { "source": "/old-path", "destination": "/new-path", "statusCode": 302 } ]}

使用 301 永久重定向将请求从 /template-source ，重定向到外部站点的绝对路径 https://github.com/TencentEdgeOne/pages-templates/tree/main/examples/chrome-ai ：

{ "redirects": [ { "source": "/template-source", "destination": "https://github.com/TencentEdgeOne/pages-templates/tree/main/examples/chrome-ai", "statusCode": 301 } ]}

使用 301 永久重定向将非 www 请求重定向到 www，同时也支持反向重定向（仅对自定义域名生效）：

{ "redirects": [ { "source": "$host", "destination": "$wwwhost", "statusCode": 301 } ]}

六、rewrites

将所有以 /assets/ 开头的请求重写到 /assets-new/ 目录下，同时保留原始请求的路径部分。

{ "rewrites": [ { "source": "/assets/*", "destination": "/assets-new/:splat" } ]}

以下示例仅重写 /assets/ 目录中的 PNG 文件，并保留文件名。

{ "rewrites": [ { "source": "/assets/*.png", "destination": "/assets-new/:splat.png" } ]}

七、SPA 前端路由

对于以 /index.html 为入口的单页应用，可通过以下配置显式声明 SPA fallback：

{ "rewrites": [ { "source": "/*", "destination": "/index.html" } ]}

Makers 会将该精确配置识别为 SPA fallback：请求优先匹配项目中的其他路由（包括静态资源和函数），仅在未命中任何其他路由时返回 /index.html，并交由前端路由处理。该规则不会作为普通重写规则生效。

八、headers

自定义和管理 HTTP 响应头，以改善网站的性能和安全性，同时提升用户体验。

通过为所有请求设置 X-Frame-Options 头部来增强网站的安全性，防止点击劫持攻击；同时，通过 Cache-Control 指定响应可以被缓存 2 小时，以提高性能和减少服务器负担。

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

进一步优化特定资源的缓存策略，针对 /assets/ 目录下的静态资源进行处理。此示例将为该目录下的所有文件设置更长的缓存时间。

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

九、URL 路径匹配规则

在 redirects、rewrites 和 headers 中，source 用于匹配请求 URL 路径；destination 可引用 source 中捕获的参数。

注意：说明：

十、includeFiles

如果你的 Node.js 函数需要直接读取文件，需要配置 includeFiles 列表，构建器会把这些文件复制到构建产物中让函数在部署后能够正确读取到这些文件。路径的格式是相对于项目根目录的相对路径(不要以./或/开头)，支持 glob 模式。

{ "cloudFunctions": { "nodejs": { "includeFiles": [ "assets/**", "assets2/**/*.json", // glob 模式 "public/font-example.ttf", // 精确匹配 "assets/**", // 包含 assets 目录下所有文件 "!assets/**/*.tmp", // 但排除所有 .tmp 文件 "assets/images/**/*.{png,jpg,jpeg,gif,webp}" // 图片资源 ] } }}

目前仅支持在函数代码中使用相对路径引入文件：

import { readFileSync } from 'fs';export function onRequest() { const image = readFileSync('../../assets/your-file.png'); return new Response(image);}

十一、externalNodeModules

Node.js 函数有一些依赖包包含原生模块或者静态文件，需要配置 externalNodeModules，让构建器能够正确分离出这些依赖并复制到构建产物中。

{ "cloudFunctions": { "nodejs": { "externalNodeModules": [ "svg-captcha" ] } }}

十二、maxDuration

Cloud Functions 的最大单次运行时长限制，可配置范围为 10 – 120 秒，不配置时默认 30 秒，不同运行时需单独设置。

{ "cloudFunctions": { "nodejs": { "maxDuration": 60 }, "python": { "maxDuration": 60 }, "go": { "maxDuration": 60 } }}

十三、mainlandRegions / overseasRegions

指定 Cloud Functions 的部署地域，覆盖控制台中的函数地域配置。mainlandRegions 设置中国大陆地域（默认 ap-guangzhou），overseasRegions 设置中国大陆以外地域（默认 ap-singapore），每个数组中只能配置一个地域 ID。详细说明请参阅 Cloud Functions 多地域部署。

{ "cloudFunctions": { "mainlandRegions": ["ap-beijing"], "overseasRegions": ["ap-tokyo"] }}

十四、schedules

配置定时任务，按照 cron 表达式周期性地触发指定的 Makers Functions。

{ "schedules": [ { "name": "daily-cleanup", "cron": "0 2 * * *", "path": "/api/cron/cleanup" } ]}

每个定时任务对象支持以下字段：

cron 表达式速查：

┌───────────── 分 (0-59)│ ┌───────────── 时 (0-23)│ │ ┌───────────── 日 (1-31)│ │ │ ┌───────────── 月 (1-12)│ │ │ │ ┌───────────── 周几 (0-7, 0 和 7 都是周日)│ │ │ │ │* * * * *

十五、agents

用于配置项目中 AI Agent 与沙箱的运行参数。

{ "agents": { "framework": "claude-agent-sdk", // claude-agent-sdk / openai-agents-sdk / langgraph / crewai / deepagents "dir": "agents", // 可选，默认 "agents" "timeout": 300, // 可选，单次任务执行的最大秒数（30 ~ 1800） "sandbox": { "timeout": 300 // 可选，沙箱实例存活时长（300 ~ 3600） } }}

Agent 的开发与使用方式可先参考 Agents。

十六、edgeone.json 文件示例

如下示例展示了如何将多个设置组合在一个配置文件中，包括但不限于所有可用选项。请注意，文件中的每个设置项并非必需。

{ "name": "example-app", "buildCommand": "next build", "installCommand": "npm install", "outputDirectory": "./build", "nodeVersion": "22.11.0", "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" } ], "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" } ] } ], "cloudFunctions": { "mainlandRegions": ["ap-guangzhou"], "nodejs": { "externalNodeModules": [ "svg-captcha" ], "includeFiles": [ "assets/**" ], "maxDuration": 60 } }}