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

除了通过控制台进行项目设置，您还可以在项目根目录下创建 edgeone.json 文件，来定义和覆盖项目的默认行为，以便更灵活地配置项目。
配置文件包括以下设置项：
buildCommand
覆盖 控制台 > Pages 项目 > 项目设置 > 构建部署配置 中的构建命令。
{
    "buildCommand": "next build"
}
installCommand
覆盖 控制台 > Pages 项目 > 项目设置 > 构建部署配置 中的安装命令。此配置项可自定义构建过程使用的 包管理器。
{
    "installCommand": "npm install"
}
outputDirectory
覆盖 控制台 > Pages 项目 > 项目设置 > 构建部署配置 中的输出目录。
{
    "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
      }
    ]
}
注意：
redirect 最大数量限制为 100 个。
source 与 destination 不超过 500 个字符。
rewrites
将所有以 /assets/ 开头的请求重写到 /assets-new/ 目录下，同时保留原始请求的路径部分。
{
    "rewrites": [
      {
        "source": "/assets/*",
        "destination": "/assets-new/:splat"
      }
    ]
}
进一步细化重写规则，专门针对 PNG 格式的图像文件进行处理。以下示例将确保所有以 .png 结尾的请求都被重写到新的路径，同时保留文件名。
{
    "rewrites": [
      {
        "source": "/assets/*.png",
        "destination": "/assets-new/:splat.png"
      }
    ]
}
注意：
rewrite 最大数量限制为 100 个。
source 与 destination 不超过 500 个字符。
该配置仅适用于静态资源访问。
不支持 SPA (单页应用) 的前端路由重写。
源路径必须以 `/` 开头。
﻿
SPA 应用重写建议：如需在 SPA 中实现 URL 重写，建议采用以下方案：
前端路由重定向
使用框架自带的路由系统进行路径重定向。
在路由配置中定义重写规则。
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"
          }
        ]
      }
    ]
}
注意：
header 最大数量限制为 30 个。
每个 header 的 key 限制为 1 - 100 个字符，允许使用数字、字母及特殊符号 '-'。
每个 header 的 value 限制为 1 - 1000 个字符，不支持中文。
source 匹配规则说明
在配置 redirects、rewrites、headers 和 caches 时，source 字段用于定义请求路径的匹配规则。以下是主要的匹配特性：
1.路径匹配
source 支持使用特定的模式来匹配请求路径。匹配规则会根据请求的 URL 进行解析。
2.通配符
使用星号（*）作为通配符，可以匹配路径中的任意字符。请注意，source 中只能包含一个通配符。
3.占位符
占位符以冒号（:）开头，后跟占位符名称。每个占位符只能在 source 中使用一次，并且会匹配除分隔符外的所有字符。
说明：
如需了解更多自定义配置用法，请参见 GitHub TencentEdgeOne。
cloudFunctions
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 表达式周期性地触发指定的 Pages Functions。
{
  "schedules": [
    {
      "name": "daily-cleanup",
      "cron": "0 2 * * *",
      "path": "/api/cron/cleanup"
    }
  ]
}
每个定时任务对象支持以下字段：
参数
类型
必填
默认值
说明
name
string
是
-
定时任务的唯一标识名，同一项目内不可重复，最长 128 字符。
cron
string
是
-
标准 5 段 cron 表达式（分 时 日 月 周）。例如：0 10 * * * 每天 10点，0 0 1 * * 每月1号。不支持秒级（6 段格式）。
path
string
是
-
要触发的 Pages Functions 路径。例如 /api/cron/tick、/api/scheduled/report。
method
enum
否
POST
触发请求的 HTTP 方法。可选值：GET、POST、PUT、DELETE、PATCH、HEAD。
payload
object
否
-
随请求发送的 JSON 数据体。仅在 method 为 POST/PUT/PATCH 时有意义，可用于传递任务参数。
timezone
string
否
构建时本机时区
cron 表达式的时区上下文。使用 IANA 时区标识符，如 Asia/Shanghai、America/New_York、UTC。若不填，CLI 构建时自动取本地系统时区写入。
cron 表达式速查：
┌───────────── 分 (0-59)
│ ┌───────────── 时 (0-23)
│ │ ┌───────────── 日 (1-31)
│ │ │ ┌───────────── 月 (1-12)
│ │ │ │ ┌───────────── 周几 (0-7, 0 和 7 都是周日)
│ │ │ │ │
* * * * *
表达式
含义
0 * * * *
每小时整点
0 9 * * *
每天 09:00
0 9 * * 1-5
工作日 09:00
0 0 1 * *
每月 1 号 00:00
0 0 * * 0
每周日 00:00
注意：
cron 最小精度为一分钟，最小间隔为一天，实际触发时间可能有秒级偏差，属于正常行为。
每次部署时平台会自动对比配置，新部署中已移除的任务会被自动停止和删除。
如果团队成员分布在不同时区，建议显式指定 timezone 字段，避免定时任务的执行时间受构建机器所在时区影响。
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
    }
  }
}
﻿
﻿

参数	类型	必填	默认值	说明
name	string	是	-	定时任务的唯一标识名，同一项目内不可重复，最长 128 字符。
cron	string	是	-	标准 5 段 cron 表达式（分时日月周）。例如：`0 10 * * ` 每天 10点，`0 0 1 *` 每月1号。不支持秒级（6 段格式）。
path	string	是	-	要触发的 Pages Functions 路径。例如 `/api/cron/tick`、`/api/scheduled/report`。
method	enum	否	POST	触发请求的 HTTP 方法。可选值：GET、POST、PUT、DELETE、PATCH、HEAD。
payload	object	否	-	随请求发送的 JSON 数据体。仅在 method 为 POST/PUT/PATCH 时有意义，可用于传递任务参数。
timezone	string	否	构建时本机时区	cron 表达式的时区上下文。使用 IANA 时区标识符，如 `Asia/Shanghai`、`America/New_York`、`UTC`。若不填，CLI 构建时自动取本地系统时区写入。

表达式	含义
`0 * * * *`	每小时整点
`0 9 * * *`	每天 09:00
`0 9 * * 1-5`	工作日 09:00
`0 0 1 * *`	每月 1 号 00:00
`0 0 * * 0`	每周日 00:00

edgeone.json

本页目录：

buildCommand

installCommand

outputDirectory

nodeVersion

redirects

rewrites

headers

source 匹配规则说明

cloudFunctions

includeFiles

externalNodeModules

maxDuration

mainlandRegions / overseasRegions

schedules

edgeone.json 文件示例