# @cloudflare/pages-functions 中文文档

规范地址：https://npmcn.com/package/%40cloudflare/pages-functions/

版本：0\.1\.7
npm 元数据更新时间：2026-11-09T14:50:26.473Z
中文译文更新时间：2026-11-10T03:22:26.631Z
软件包许可：MIT OR Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cloudflare/pages-functions
原文对照：https://npmcn.com/package/%40cloudflare/pages-functions/?lang=original
项目主页：https://github.com/cloudflare/workers-sdk/tree/main/packages/pages-functions#readme
源码仓库：https://github.com/cloudflare/workers-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.5 MB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：2 个
- 首次发布：2026-07-30T09:09:03.060Z
- 最新版本发布：2026-11-09T14:50:25.944Z
- 近 30 天下载量：8327（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

将 Pages 函数目录编译为 Cloudflare 工作包

## 安装

```sh
npm install @cloudflare/pages-functions
```

也可以使用：`pnpm add @cloudflare/pages-functions`、`yarn add @cloudflare/pages-functions`、`bun add @cloudflare/pages-functions`

## README

# `@cloudflare/pages-functions`

`@cloudflare/pages-functions` 编译 a [云花板页函数](https://developers.cloudflare.com/pages/functions/) `functions/` 目录为单 [云花岗工人](https://developers.cloudflare.com/workers/) 捆绑 它既提供了命令行界面,也提供了用于构建工具的程序API.

软件包发现基于文件的路由,将他们的处理器捆绑入ES模块Worker,收集所导入的Wasm,文本,和二进制模块,并通过它的API返回Page路由元数据.

> \[尖叫声\] 不建议新开发功能 。 与Workers建立新的应用程序和新的服务器侧功能. 这一一揽子计划旨在支持现有的Pages函数项目,并帮助逐步将其迁移到工人手中.

## 安装

将软件包安装为开发依赖 :

```sh
npm install --save-dev @cloudflare/pages-functions
```

## 国 际

编译默认 `functions/` 输入目录 `dist/`数字 :

```sh
npx @cloudflare/pages-functions build
```

要指定输入和输出目录:

```sh
npx @cloudflare/pages-functions build ./functions --outdir ./dist/worker
```

命令写出以下文件:

-   `index.js`: 编译的ES模块
-   `index.js.map`: 源图, 当 `--sourcemap` 用于
-   导入的瓦姆、文本、 二进制和 `assets:` 工人所需的模块

生成的工人包含自己的路由器,不需要 `_routes.json` 文档。 生成一个( 例如在部署到 Pages 时), 通过 `--routes-output <path>`。页面部署工具,如 Wrangler , 自动生成此文件, 不需要 CLI .

命令只构建"工人". 它不部署它或创建部署配置。 默认情况下,生成的工人返回到 `env.ASSETS.fetch()` 当没有函数路由处理请求时, 部署必须提供 `ASSETS` 约束或选择其他约束 `--fallback-service`。 。 。 .

运行时本地进口,例如 `node:*` 财务报告和审定财务报表 `cloudflare:*` 不被自动排除在捆绑之外。 以可重复的方式传过去 `--external` 选项,当周围的工人构建或运行时间提供:

```sh
npx @cloudflare/pages-functions build --external "node:*" --external "cloudflare:*"
```

### CLI 选项

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `[directory]` | 页面函数目录 | `functions` |
| `--outdir <path>` | 输出目录 | `dist` |
| `--minify` | 减少工人捆绑 | 已禁用 |
| `--sourcemap` | 生成外部源图 | 已禁用 |
| `--fallback-service <name>` | 在没有路由处理请求时使用的抓取器绑定 | `ASSETS` |
| `--external <module>` | 从捆绑中排除模块; 可重复 | 无 |
| `--routes-output <path>` | 写入生成 `_routes.json` 显示此路径 | 未写入 |
| `-h`, (中文(简体) ), `--help` | 显示使用信息 |  |
| `-v`, (中文(简体) ), `--version` | 显示软件包版本 |  |

## 程序化 API

使用 `buildPagesFunctions()` 当将编译器集成到另一个构建工具时:

```ts
import { buildPagesFunctions } from "@cloudflare/pages-functions";

const result = await buildPagesFunctions({
    functionsDirectory: "./functions",
    outputDirectory: "./dist/worker",
    sourcemap: true,
});

console.log(result.entryPointPath);
console.log(result.routesJSON);
```

`buildPagesFunctions()` 返回生成的路由规格为 `routesJSON` 但不写 `_routes.json` 文档。 Wrangler等消费者在部署到Pages时可以使用这个元数据.

### 构建选项

| 选项 | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| `functionsDirectory` | `string` | 要编译的 Pages 函数目录 | 需求 |
| `outputDirectory` | `string` | 目录 `index.js` 和收集的模块 | 需求 |
| `assetsOutputDirectory` | `string` | 引用文件目录 `assets:` 进口 | `outputDirectory` |
| `fallbackService` | `string` | 在没有路由处理请求时使用的抓取器绑定 | `ASSETS` |
| `minify` | `boolean` | 减少工人捆绑 | `false` |
| `sourcemap` | `boolean` | 生成外部源图 | `false` |
| `external` | `string[]` | 从捆绑中排除的模块指定符 | `undefined` |
| `routesDescription` | `string` | 返回路线规格中的描述 | `undefined` |
| `metafile` | `boolean` | 在结果中包含构建元文件 | `false` |

### 构建结果

`buildPagesFunctions()` 返回 :

| 财产 | 说明 |
| --- | --- |
| `entryPointPath` | 生成的绝对路径 `index.js` |
| `bundleType` | 永远 `"esm"` |
| `modules` | 收集的瓦姆、文本和二进制模块 |
| `dependencies` | 输入包含在生成的捆绑中 |
| `sourceMapPath` | 启用源地图时的绝对源地图路径 |
| `routesJSON` | 已生成 `_routes.json` 数据 |
| `filepathRoutingConfig` | 函数路由和基址 |
| `metafile` | 应要求建立元文件 |

软件包还会输出低级路由发现,生成,优化,以及用于工具作者的验证帮助. 他们的TypeScript声明包含在包中.

## 向工人迁移

[工人静态资产](https://developers.cloudflare.com/workers/static-assets/) 支持一起部署前端资产和工人代码。 工人还提供比Pages函数更多的Cloudflare平台功能. 因此,新的路线和应用程序逻辑应该写在工人身上,而不是添加到现有的 `functions/` 目录.

对于已有的 Pages 函数项目,您可以在工人构建过程中编译旧函数,并授权您工人向它们提出请求。 这让你一次迁移一条路线.

例如,配置Wrangler来编译遗产 `functions/` 绑定工作人之前的目录 :

```jsonc
{
    "$schema": "./node_modules/wrangler/config-schema.json",
    "name": "my-worker",
    "main": "./src/index.js",
    // Preserve the compatibility date and flags from your Pages project.
    "compatibility_date": "<YOUR_EXISTING_COMPATIBILITY_DATE>",
    "assets": {
        "directory": "./dist/client",
        "binding": "ASSETS",
        "run_worker_first": true,
    },
    "build": {
        "command": "npx @cloudflare/pages-functions build ./functions --outdir ./dist/pages-functions --external \"node:*\" --external \"cloudflare:*\"",
        "watch_dir": ["./functions", "./src"],
    },
}
```

调整 `assets.directory` 并按需要将构建命令与您现有的前端构建命令合并。 保存 Pages 工程所用的任何兼容标记 。 这个 `--external` 选项留给Wrangler处理运行时本地进口。 这个 `ASSETS` 绑定是由编译器默认倒置行为要求的. `run_worker_first` 确保工人在回归到静态资产之前可以运行 Pages 函数路由和中间软件.

从 Worker 导入已编译的处理器, 先处理新路由或迁移的路由, 并使用旧的 Pages 函数处理器作为倒置 :

```js
import legacyPagesFunctions from "../dist/pages-functions/index.js";

export default {
    async fetch(request, env, ctx) {
        const url = new URL(request.url);

        if (url.pathname === "/api/new-route") {
            return new Response("Handled by the Worker");
        }

        return legacyPagesFunctions.fetch(request, env, ctx);
    },
};
```

此命令意味着 Pages 函数中间软件不会运行到由工人直接处理的路由 。 在移动依赖于它的路线之前,向工人移动认证、授权、记录和其他适用的中间软件.

随着路由迁移,将文件从 `functions/` 并在工人中直接执行。 一旦不再保留遗留的 Pages 函数,请删除编译器构建步骤并导入 .

如果遗留函数使用 `assets:` 输入时,输入的资产必须写入所配置的目录 `assets.directory`。CLI将其写在其输出目录下,因此使用程序API来选择单独的工人和资产输出:

```js
// scripts/build-pages-functions.mjs
import { buildPagesFunctions } from "@cloudflare/pages-functions";

await buildPagesFunctions({
    functionsDirectory: "./functions",
    outputDirectory: "./dist/pages-functions",
    assetsOutputDirectory: "./dist/client",
    external: ["node:*", "cloudflare:*"],
});
```

准备 `build.command` 改为 `node ./scripts/build-pages-functions.mjs`编辑 `assets:` 集成总是使用 `ASSETS` 绑定,即使配置了不同的一般倒置服务.

工人不使用页 `_routes.json` 元数据。 配置 [静态资产路线](https://developers.cloudflare.com/workers/static-assets/routing/) 明确,特别是如果页面项目使用自定义 `_routes.json` 规则或中间软件。 见完整 [页数与工人迁移指南](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/) 用于绑定、资产、兼容性设置和部署变化.

## 捐款

见工人SDK [贡献指南](https://npmcn.com/package/CONTRIBUTING.md) 用于储存库的设置和捐款要求.

从寄存器根处安装依赖性并运行包任务 :

```sh
pnpm install
pnpm run build --filter @cloudflare/pages-functions
pnpm run check:type --filter @cloudflare/pages-functions
pnpm run test:ci --filter @cloudflare/pages-functions
pnpm run dev --filter @cloudflare/pages-functions
```

这个 `dev` 任务监视此软件包的执行; 它不监视终端用户 Pages 函数项目.

提交更改前, 运行 :

```sh
pnpm prettify
pnpm check
```

## 许可证

许可证根据 [Apache 2.0 许可证](https://npmcn.com/package/LICENSE-APACHE) 或 [麻省理工学院许可证](https://npmcn.com/package/LICENSE-MIT) 随便你.

## 常见问题

### @cloudflare/pages-functions 是什么？

将 Pages 函数目录编译为 Cloudflare 工作包

### 如何安装 @cloudflare/pages-functions？

在项目目录运行 npm install @cloudflare/pages-functions，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 pages-functions，可以用 npx pages-functions 直接运行。

### @cloudflare/pages-functions 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cloudflare/pages-functions 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cloudflare/pages-functions 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cloudflare/pages-functions 可以商用吗？

@cloudflare/pages-functions 使用 MIT OR Apache-2\.0 许可。可在 MIT、Apache-2\.0 中任选其一遵守。选择 MIT 时，宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cloudflare/pages-functions 的下载量有多少？

根据 npm 官方下载统计，@cloudflare/pages-functions 在 2026/10/10 – 2026/11/08 这 30 天内被下载 8,327 次，日均约 278 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cloudflare/pages-functions 还在维护吗？

最新版本 0\.1\.7 发布于 2026/11/09（今天）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/07/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。