@cloudflare/pages-functions

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

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

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

安装

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

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

国 际

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

npx @cloudflare/pages-functions build

要指定输入和输出目录:

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 选项,当周围的工人构建或运行时间提供:

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

CLI 选项

程序化 API

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

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时可以使用这个元数据.

构建选项

构建结果

buildPagesFunctions() 返回 :

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

向工人迁移

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

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

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

{
    "$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 函数处理器作为倒置 :

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来选择单独的工人和资产输出:

// 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 元数据。 配置 静态资产路线 明确,特别是如果页面项目使用自定义 _routes.json 规则或中间软件。 见完整 页数与工人迁移指南 用于绑定、资产、兼容性设置和部署变化.

捐款

见工人SDK 贡献指南 用于储存库的设置和捐款要求.

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

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 函数项目.

提交更改前, 运行 :

pnpm prettify
pnpm check

许可证

许可证根据 Apache 2.0 许可证 或 麻省理工学院许可证 随便你.