路由

Functions 使用基于文件的路由。/functions 目录结构决定 Functions 运行的指定路由。可根据项目用例创建任意层级的 /functions 目录。查看以下目录：

根据上述文件结构将生成以下路由。这些路由将 URL 模式映射到访问 URL 时将调用的 /functions 文件：

若无 Function 匹配，将回退到静态资源（若有）。否则，Function 将回退到 Pages 静态资源的 默认路由行为。

动态路由允许你匹配带参数化段的 URL。若你正在构建动态应用，这很有用。可通过更改文件名来接受映射到单一路径的动态值。

要创建动态路由，在文件名周围放置一组方括号——例如 /users/[user].js。这样会为单个路径段创建占位符：

在文件名周围放置两组方括号——例如 /users/[[user]].js——可匹配 /users/ 之后的任意深度路由：

查看以下 /functions/ 目录结构：

以下请求将匹配以下文件：

匹配占位符（[user]）的 URL 段可在请求 context 对象中获取。context.params 对象可用于查找给定文件名占位符的匹配值。

对于匹配单个 URL 段的文件（使用单组方括号），值以字符串返回：

export function onRequest(context) {
	return new Response(context.params.user);
}

上述逻辑对 /users/daniel 的请求将返回 daniel。

对于匹配多个 URL 段的文件（使用双组方括号），值以数组返回：

export function onRequest(context) {
	return new Response(JSON.stringify(context.params.catchall));
}

上述逻辑对 /users/daniel/xyz/123 的请求将返回 ["daniel", "xyz", "123"]。

在纯静态项目中，Pages 提供无限免费请求。但在 Pages 项目中添加 Functions 后，默认所有请求都会调用 Function。若要继续获得无限免费静态请求，请通过创建 _routes.json 文件排除项目的静态路由。使用 Pages CI 或 Wrangler 发布项目时，若检测到 functions 目录，此文件将自动生成。

创建 _routes.json 文件以控制 Function 何时被调用。应将其放在项目的构建目录中。

此文件包含三个不同属性：

• version：定义 schema 版本。目前 schema 只有一个版本（版本 1），但未来可能添加更多，并力求向后兼容。
• include：定义由 Functions 调用的路由。支持通配符。
• exclude：定义不由 Functions 调用的路由。支持通配符。exclude 始终优先于 include。

以下是 _routes.json 的示例。

{
	"version": 1,
	"include": ["/*"],
	"exclude": []
}

此 _routes.json 将在所有路由上调用 Functions。

以下是另一个 _routes.json 文件示例。/build 目录内的任何路由都不会调用 Function，也不会产生 Functions 调用费用。

{
	"version": 1,
	"include": ["/*"],
	"exclude": ["/build/*"]
}

若在 Workers 免费计划上，可配置 Pages Functions 每日免费配额用尽时的行为。例如，若你在 Pages Functions 中执行身份验证检查或其他关键功能，可能希望在配额用尽时禁用 Pages 项目。

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择你的 Pages 项目。

3. 前往 Settings（设置） > Runtime（运行时） > Fail open / closed。

"Fail open" 表示即使 Pages Functions 通常会先运行，静态资源仍会继续提供。"Fail closed" 表示返回错误页面，而非静态资源。

升级到 Workers Standard 可完全移除 Pages Functions 的每日请求限制。

Functions 调用路由有以下限制：

• 必须至少有一条 include 规则。
• include/exclude 规则合计不得超过 100 条。
• 每条规则不得超过 100 个字符。