@astrojs/cloudflare

@astrojs/cloudflare 是一个与 Cloudflare Pages Functions 目标一起使用的 SSR 适配器。你可以使用 Astro/Javascript 编写代码，并将其部署到 Cloudflare Pages。

安装

通过以下 astro add 命令将 Cloudflare 适配器添加到你的 Astro 项目中，以启用 SSR。这将安装适配器，并在这一步之内对 astro.config.mjs 文件进行相应的更改。

# 使用 NPM
npx astro add cloudflare
# 使用 Yarn
yarn astro add cloudflare
# 使用 PNPM
pnpm astro add cloudflare

如果你更喜欢手动安装适配器，请完成以下两个步骤：

1. 使用你喜欢的包管理器安装 Cloudflare 适配器到项目的依赖项中。如果你使用 npm 或不确定，可以在终端中运行：

npm install @astrojs/cloudflare

2. 将以下内容添加到你的 astro.config.mjs 项目文件中：

astro.config.mjs

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
});

选项

mode

mode: "advanced" | "directory"

默认为 "advanced"

这个配置选项定义了你的 Astro 项目如何部署到 Cloudflare Pages。

• advanced 模式会获取 dist 文件夹中的 _worker.js 文件。
• directory 模式会获取 functions 文件夹中的文件，默认只会生成一个 [[path]].js 文件。

切换到 directory 模式允许你手动添加额外的文件例如 Cloudflare Pages 插件、Cloudflare Pages 中间件 甚至使用了 Cloudflare Pages 函数路由 的自定义函数。

astro.config.mjs

export default defineConfig({
  adapter: cloudflare({ mode: 'directory' }),
});

要为每个页面编译单独的包，请在你的 Cloudflare 适配器配置中设置 functionPerRoute 选项。该选项需要手动维护 functions 文件夹。Astro 生成的文件将覆盖 functions 文件夹中具有相同名称的现有文件，因此你必须为手动添加的每个文件选择唯一的文件名。此外，适配器永远不会清空 functions 文件夹中过时的文件，因此当你删除页面时，你必须手动清理文件夹。

astro.config.mjs

import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    mode: 'directory',
    functionPerRoute: true
  })
})

该适配器不支持 edgeMiddleware 选项。

routes.strategy

routes.strategy: "auto" | "include" | "exclude"

默认值："auto"

在没有提供自定义 _routes.json 的情况下决定 routes.json 该如何被生成。

这有三个选项可供选择：

• "auto"（默认）：自动选择生成最少条目的策略。这通常应该够用了，除非你有某些理由要选择其他选项。

• include：不会被预渲染的页面和端点将会被列为 include 条目，并告诉 Cloudflare 将这些路由作为函数调用。而 exclude 条目仅用于解决冲突。通常情况下，如果你的网站大多数是静态页面，只有少数动态页面或端点时，这将是最好的策略。

  示例：对于 src/pages/index.astro（静态），src/pages/company.astro（静态），src/pages/users/faq.astro（静态），以及 /src/pages/users/[id].astro （SSR），将产生以下 _routes.json:

  {
    "version": 1,
    "include": [
      "/_image", // Astro 的图片端点
      "/users/*" // 动态路由
    ],
    "exclude": [
      // 排除上述动态通配符路由中后的静态路由
      "/users/faq/",
      "/users/faq/index.html"
    ]
  }

• exclude： 预渲染的页面将被列为 exclude 条目（即告诉 Cloudflare 将这些路由作为静态资源处理）。通常情况下，如果你的网站大多数是动态页面或端点，只有少数静态页面时，这将是最好的策略。

  示例：对于前面示例中相同的页面，这将产生以下 _routes.json:

  {
    "version": 1,
    "include": [
      "/*" // 除了后面的路由外，所有路由都会被作为函数处理
    ],
    "exclude": [
      // 所有静态资源
      "/",
      "/company/",
      "/index.html",
      "/users/faq/",
      "/favicon.png",
      "/company/index.html",
      "/users/faq/index.html"
    ]
  }

routes.include

routes.include: string[]

默认值：[]

如果你想使用自动生成的 _routes.json，但又想要包含额外的路由（例如，当你在 functions 文件夹中有自定义函数时），那么你可以使用 routes.include 选项将额外的路由添加到 include 数组中。

routes.exclude

routes.exclude: string[]

默认值：[]

如果你想要使用自动生成的 _routes.json，但又想要排除其他的路由，那么你可以使用 routes.exclude 选项将额外的路由到添加 exclude 数组中。

以下示例自动生成了 _routes.json，同时包含和排除额外的路由。请注意，如果你在 functions 文件夹中有自定义函数，那么这些函数将不会被 Astro 处理。

astro.config.mjs

export default defineConfig({
  adapter: cloudflare({
    mode: 'directory',
    routes: {
      strategy: 'include',
      include: ['/users/*'], // 由自定义函数处理：functions/users/[id].js
      exclude: ['/users/faq'], // 由静态页面处理：pages/users/faq.astro
    },
  }),
});

imageService

imageService: "passthrough" | "cloudflare"

控制适配器使用哪个图像服务。当配置了不兼容的图像服务时，适配器将默认到 passthrough 模式。否则，它将使用全局配置的图像服务：

• cloudflare: 使用 Cloudflare Image Resizing 服务。
• passthrough: 使用现有的 noop 服务。

wasmModuleImports

wasmModuleImports: boolean

默认值：false

是否将 .wasm 文件直接作为 ES 模块导入。

将 wasmModuleImports: true 添加到 astro.config.mjs 以在 Cloudflare 构建和 Astro 开发服务器中启用该功能。

astro.config.mjs

import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
    adapter: cloudflare({
      wasmModuleImports: true
    }),
    output: 'server'
})

runtime

runtime: { mode: "off" | "local", persistTo: string }

默认值：{ mode: 'off', persistTo: '' }

决定是否以及如何将 Cloudflare Runtime 添加到 astro dev。

Cloudflare Runtime 包括 Cloudflare 绑定、环境变量 和 cf 对象。参阅有关 访问 Cloudflare Runtime 的更多信息。

mode 属性定义了如何将运行时添加到 astro dev：

• local：使用绑定模拟和本地静态占位符。
• off：astro dev 不会访问 Cloudflare 运行时。你也可以通过 使用 Wrangler 预览。

persistTo 属性定义了在使用 mode: local 时本地运行时的持久化位置。该值是相对于你的 astro dev 执行路径的目录。

默认值为 .wrangler/state/v3，以匹配 Wrangler 使用的默认路径。这意味着两个工具都能够访问和使用本地状态。

不论你在 persistTo 中设定了哪一个目录，比如 .wrangler 或你自定义的值，都必须将其添加到 .gitignore 中。

astro.config.mjs

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare({
   runtime: { mode: 'local' },
  }),
});

Cloudflare 运行时

你可以访问 环境变量 和 Cloudflare 绑定。

目前支持的绑定有：

• Cloudflare D1
• Cloudflare R2
• Cloudflare Workers KV
• Cloudflare Durable Objects

在任意 .astro 文件中，你都可以直接通过 Astro.locals 从 Astro 组件中访问运行时：

src/pages/index.astro

---
const runtime = Astro.locals.runtime;
---
<pre>{JSON.stringify(runtime.env)}</pre>

你也可以通过 context.locals 从 API 端点访问运行时：

src/pages/api/someFile.js

export function GET(context) {
  const runtime = context.locals.runtime;
  return new Response('Some body');
}

类型

如果你正在使用 advanced 运行时，那么你可以按以下方式声明 runtime 对象：

如果你已经配置了 mode:advanced，你可以使用 AdvancedRuntime 来为 runtime 对象添加类型：

src/env.d.ts

/// <reference types="astro/client" />

type KVNamespace = import('@cloudflare/workers-types/experimental').KVNamespace;
type ENV = {
  SERVER_URL: string;
  KV_BINDING: KVNamespace;
};

type Runtime = import('@astrojs/cloudflare').AdvancedRuntime<ENV>;

declare namespace App {
  interface Locals extends Runtime {
    user: {
      name: string;
      surname: string;
    };
  }
}

如果你已经配置了 mode: directory，你可以使用 DirectoryRuntime 来为 runtime 对象添加类型：

src/env.d.ts

/// <reference types="astro/client" />

type KVNamespace = import('@cloudflare/workers-types/experimental').KVNamespace;
type ENV = {
  SERVER_URL: string;
  KV_BINDING: KVNamespace;
};

type Runtime = import('@astrojs/cloudflare').DirectoryRuntime<ENV>;

declare namespace App {
  interface Locals extends Runtime {
    user: {
      name: string;
      surname: string;
    };
  }
}

平台

标头

你可以通过在 Astro 项目的 public/ 文件夹中添加一个 _headers 文件来附加 自定义头部 到你的响应中，该文件将被复制到构建输出目录中。

重定向

你可以使用 Cloudflare Pages 来声明 自定义重定向。这允许你将请求重定向到不同的 URL。你可以在 Astro 项目的 public/ 文件夹中添加一个 _redirects 文件，该文件将被复制到构建输出目录。

路由

你可以使用 Cloudflare 路由 通过 _routes.json 文件来定义哪些路由会调用函数，哪些路由是静态资源。该文件由 Astro 自动生成。

自定义 _routes.json

默认情况下，@astrojs/cloudflare 会基于你应用的动态和静态路由生成一个 _routes.json 文件，当中包含了 include 和 exclude 规则。

这将使 Cloudflare 能够在没有函数调用的情况下提供文件和处理静态重定向。创建自定义的 _routes.json 将覆盖此自带的优化文件。参阅 Cloudflare 关于创建自定义 routes.json 的文档 了解更多细节。

使用 Wasm 模块

以下是导入一个 Wasm 模块的示例，该模块通过将请求的数字参数相加来响应请求：

pages/add/[a]/[b].js

import mod from '../util/add.wasm?module';

// 预先初始化以共享同一个模块
const addModule: any = new WebAssembly.Instance(mod);

export async function GET(context) {
  const a = Number.parseInt(context.params.a);
  const b = Number.parseInt(context.params.b);
  return new Response(`${addModule.exports.add(a, b)}`);
}

虽然这个例子很简单，但是 Wasm 可以用来加速在不涉及大量 I/O 的情况下的计算密集型操作，比如嵌入图像处理库。

Node.js 兼容性

Astro 的 Cloudflare 适配器允许你使用任何 Cloudflare 支持的 Node.js 运行时 API，例如：

• assert
• AsyncLocalStorage
• Buffer
• Crypto
• Diagnostics Channel
• EventEmitter
• path
• process
• Streams
• StringDecoder
• util

如果要使用这些 API，你的页面或端点必须是服务器渲染的（而不是预渲染的），并使用 import {} from 'node:*' 导入语法。

pages/api/endpoint.js

export const prerender = false;
import { Buffer } from 'node:buffer';

另外，你需要在 Cloudflare 中启用兼容性标志。该标志的配置方法取决于你部署 Astro 站点的方式。更多详细指导，请参阅 启用 Node.js 兼容性的 Cloudflare 文档。

Cloudflare 模块支持

所有 Cloudflare 的命名空间包（例如 cloudflare:sockets）都允许使用。但请注意，cloudflare:sockets 包在本地环境中需要使用 Wrangler 的开发模式才能正常工作。

使用 Wrangler 预览

为了使用 wrangler 在本地运行你的应用程序，请更新预览脚本：

package.json

"preview": "wrangler pages dev ./dist"

wrangler 能让你访问 Cloudflare 绑定、环境变量 和 cf 对象。要让热重载或 Astro 开发服务器与 Wrangler 工作，可能需要进行自定义设置。请参阅 社区示例。

有意义的错误消息

目前，在 Wrangler 中运行应用程序时由于代码被压缩，错误消息并不是很有用。为了更好地进行调试，你可以将 vite.build.minify = false 添加到你的 astro.config.js 文件中。

export default defineConfig({
  adapter: cloudflare(),
  output: 'server',

  vite: {
    build: {
      minify: false,
    },
  },
});

故障排除

寻求帮助，请查看 Discord 的 #support 频道。我们友好的支持团队成员会在这里提供帮助！

你还可以查看我们的 Astro 集成文档 了解更多关于集成的信息。

贡献

该软件包由 Astro 核心团队维护。欢迎提交 issue 或 PR！

其他

UI 框架

• 

  @astrojs/alpinejs

• 

  @astrojs/lit

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

SSR 适配器

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

其他

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/prefetch

• 

  @astrojs/sitemap

• 

  @astrojs/tailwind