@astrojs/ cloudflare
此适配器允许 Astro 将你的hybrid
或者 server
渲染站点部署到Cloudflare.
如果你使用 Astro 作为静态站点构建器,则不需要适配器。
在我们的 Cloudflare Pages部署指南 中了解如何部署Astro站点。
为什么选择 Astro Cloudflare
段落标题 为什么选择 Astro CloudflareCloudflare提供 CDN、网络安全和其他服务。该适配器增强了 Astro 构建过程,为你的项目通过 Cloudflare 进行部署做好准备。
安装
段落标题 安装Astro 包含了一个 astro add
命令,用于自动设置官方集成。如果你愿意,可以改为手动安装集成。
在你的 Astro 项目中使用 astro add
命令添加 Cloudflare 适配器,以启用SSR。这将安装@astrojs/cloudflare
并一步到位地对你的 astro.config.mjs
文件进行相应的更改。
手动安装
段落标题 手动安装首先,使用合适的包管理器将 @astrojs/cloudflare
适配器添加到项目的依赖项中。
然后,将适配器和所需的按需渲染模式添加到 astro.config.mjs
文件中:
选项
段落标题 选项imageService
段落标题 imageService类型: 'passthrough' | 'cloudflare' | 'compile' | 'custom'
默认值: 'passthrough'
确定适配器使用哪个图像服务。当配置了不兼容的图像服务时,适配器将默认使用 passthrough
模式。否则,它将使用全局配置的图像服务:
cloudflare
: 使用 Cloudflare 图像调整 服务。passthrough
: 使用现有的noop
服务。compile
: 使用 Astro 的默认服务(sharp),但仅在构建时对预渲染的路由有效。在服务端渲染(SSR)中,对按需渲染的页面,所有astro:assets
功能都将被禁用。custom
: 总是使用在 Image 选项 中配置的图像服务。此选项不会检查配置的图像服务是否在 Cloudflare 的workerd
运行时中工作。
platformProxy
段落标题 platformProxy决定是否以及如何将 Cloudflare 运行时添加到 astro dev
中。它包含对本地 workerd
绑定和 Cloudflare 特定值的代理和模拟,允许在 Node.js 开发过程中模拟运行时。阅读更多关于 Cloudflare 运行时 的信息。
此处提供的代理尽最大努力模拟真实生产环境。虽然它们旨在尽可能接近真实情况,但两者之间可能存在轻微的差异和不一致。
类型: { enabled?: boolean }
默认值: { enabled: false }
enabled
属性允许你在 astro dev
中启用 Cloudflare 运行时。
platformProxy.configPath
段落标题 platformProxy.configPath类型: { configPath?: string }
默认值: { configPath: 'wrangler.toml' }
configPath
允许你定义你的 Wrangler 配置文件,相对于你的 Astro 项目的根目录。
platformProxy.experimentalJsonConfig
段落标题 platformProxy.experimentalJsonConfig类型: { experimentalJsonConfig?: boolean }
默认值: { experimentalJsonConfig?: false }
experimentalJsonConfig
属性定义了该工具是否读取 JSON 配置文件(例如 wrangler.json
)。
platformProxy.persist
段落标题 platformProxy.persist类型: { persist?: boolean | { path: string } }
默认值: { persist: true }
persist
属性定义了绑定数据是否持久化以及持久化的位置。true
默认与 Wrangler 使用的位置相同,因此数据可以在两者之间共享。如果是 false
,则不会向文件系统持久化或从文件系统读取任何数据。
wrangler
的 --persist-to
选项会在底层添加一个名为 v3
的子目录,而 @astrojs/cloudflare
的 persist
属性则不会。例如,要重用与运行 wrangler dev --persist-to ./my-directory
相同的位置,你必须指定:persist: "./my-directory/v3"
。
以下配置展示了在运行开发服务器时启用 Cloudflare 运行时的示例,以及使用 wrangler.json
配置文件(实验性的)。它还指定了一个自定义位置,用于将数据持久化到文件系统中:
routes.extend
段落标题 routes.extend此选项允许你添加或排除自定义模式(例如 /fonts/*
)到生成的 _routes.json
文件中,该文件决定了哪些路由是按需生成的。如果你需要添加无法自动生成的路由模式,或排除预渲染的路由,这会很有用。
关于自定义路由模式的更多信息,可以在 Cloudflare 的路由文档中找到。指定的任何路由都不会自动去重,将会按原样添加到现有路由中。
routes.extend.include
段落标题 routes.extend.include类型: { pattern: string }[]
默认值: undefined
routes.extend.exclude
段落标题 routes.extend.exclude类型: { pattern: string }[]
默认值: undefined
在 routes.extend.exclude
数组中配置要从按需渲染中排除的路由。这些路由将预先渲染并以静态方式提供,而不会调用服务端渲染(SSR)函数。此外,你还可以使用这个选项直接提供任何静态资源(例如:图片、字体、css、js、html、txt、json 等)文件,无需通过 SSR 函数路由请求。
cloudflareModules
段落标题 cloudflareModules类型: true | false
默认值: true
此功能默认启用。如果你想禁用它,请设置 cloudflareModules: false
。
Cloudflare 运行时
段落标题 Cloudflare 运行时Cloudflare 运行时允许你访问环境变量和 Cloudflare 绑定。
Cloudflare 运行时利用在 wrangler
和 .dev.vars
配置文件中找到的绑定。
用例
段落标题 用例例如,如果你在 wrangler.toml
中设置了环境变量的配置:
如果你还需要定义 secrets
以外的环境变量,你需要在 Astro 项目的根目录下添加一个 .dev.vars
文件:
你可以像这样使用 Astro locals 来访问这些绑定的值:
你也可以通过 context.locals
从 API 端点访问运行时:
要访问 MY_VARIABLE
绑定的值,请在你的代码中添加以下内容:
请查看 Cloudflare 文档中的所有支持的绑定列表。
类型定义
段落标题 类型定义wrangler
提供了一个 types
命令来为绑定生成 TypeScript 类型。这允许你对本地变量进行类型定义,而无需手动输入它们。更多信息请参考 Cloudflare 文档。
每次更改配置文件(例如 wrangler.toml
、.dev.vars
)时,你需要运行 wrangler types
。
你可以创建一个 pnpm 脚本来自动在其他命令之前运行 wrangler types
。
你可以使用 Runtime
来为 runtime
对象添加类型:
Cloudflare 平台
段落标题 Cloudflare 平台标头
段落标题 标头你可以通过在 Astro 项目的 public/
文件夹中添加一个 _headers
文件来附加 自定义头部 到你的响应中,该文件将被复制到构建输出目录中。
资源
段落标题 资源由 Astro 构建的所有资源都以哈希命名,因此可以为它们添加长期缓存标头。默认情况下,Cloudflare 上的 Astro 会为这些文件添加这样的头。
重定向
段落标题 重定向你可以使用 Cloudflare Pages 来声明 自定义重定向。这允许你将请求重定向到不同的 URL。你可以在 Astro 项目的 public/
文件夹中添加一个 _redirects
文件,该文件将被复制到构建输出目录。
路由
段落标题 路由你可以使用 Cloudflare 路由 通过 _routes.json
文件来定义哪些路由会调用函数,哪些路由是静态资源。
自定义 _routes.json
段落标题 自定义 _routes.json默认情况下,适配器会基于你应用的动态和静态路由生成一个 _routes.json
文件,当中包含了 include
和 exclude
规则。
这将使 Cloudflare 能够在没有函数调用的情况下提供文件和处理静态重定向。创建自定义的 _routes.json
将覆盖这种自动生成的文件。参阅 Cloudflare 关于创建自定义 routes.json
的文档 了解更多细节。
Cloudflare 模块导入
段落标题 Cloudflare 模块导入Cloudflare worker 运行时支持导入一些非标准模块类型。大多数额外的文件类型在 astro 中也是可用的:
.wasm
或.wasm?module
:导出一个可以实例化的WebAssembly.Module
.bin
:导出一个文件的原始二进制内容的ArrayBuffer
.txt
:导出文件内容的字符串
所有模块类型都导出一个默认值。模块既可以从服务器端渲染的页面导入,也可以从预渲染的页面导入,以生成静态站点。
以下是导入一个 Wasm 模块的示例,该模块通过将请求的数字参数相加来响应请求:
虽然这个例子很简单,但是 Wasm 可以用来加速在不涉及大量 I/O 的情况下的计算密集型操作,比如嵌入图像处理库,或嵌入小型预索引数据库以在只读数据集上进行搜索。
Node.js 兼容性
段落标题 Node.js 兼容性默认情况下,Cloudflare 不支持 Node.js 运行时 API。但通过一些配置,Cloudflare 可以支持 Node.js 运行时 API 的一个子集。你可以在 Cloudflare 的文档中找到支持的 Node.js 运行时 API。
如果要使用这些 API,你的页面或端点必须是服务器渲染的(而不是预渲染的),并使用 import {} from 'node:*'
导入语法。
你还需要修改你的 astro 配置中的 vite
配置,以允许使用 node:*
导入语法:
此外,你还需要遵循 Cloudflare 的文档来启用支持。具体指导,请参考 Cloudflare 关于启用 Node.js 兼容性的文档。
如果一个项目将一个包导入到服务器中,而该包使用了 Node.js 运行时 API,这在部署到 Cloudflare 时可能会引起问题。这个问题出现在不使用 node:*
导入语法的包上。建议你联系包的作者,以确定该包是否支持上述导入语法。如果该包不支持这种语法,你可能需要使用另一个包。
使用 Wrangler 预览
段落标题 使用 Wrangler 预览为了使用 wrangler
在本地运行你的应用程序,请更新预览脚本:
wrangler
能让你访问 Cloudflare 绑定、环境变量 和 cf 对象。要让热重载或 Astro 开发服务器与 Wrangler 工作,可能需要进行自定义设置。请参阅 社区示例。
有意义的错误消息
段落标题 有意义的错误消息目前,在 Wrangler 中运行应用程序时由于代码被压缩,错误消息并不是很有用。为了更好地进行调试,你可以将 vite.build.minify = false
添加到你的 astro.config.js
文件中。