跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

Astro

最后更新 查看 MarkdownAgent 设置

从 CLI 开始：在 Workers 上搭建 Astro 项目，并选择模板。

npm create cloudflare@latest -- my-astro-app --framework=astro

或直接部署：使用 Astro 创建静态博客并部署到 Cloudflare Workers，CI/CD 与预览均已为你配置好。

Deploy to Workers

什么是 Astro？

Astro ↗ 是一个 JavaScript Web 框架，用于创建展示大量内容的网站（例如博客、文档站点或在线商店）。

Astro 通过尽可能减少客户端 JavaScript 来强调性能——默认情况下，它会在构建时渲染尽可能多的内容，或在「服务器」上按需 ↗渲染——该服务器可以是 Cloudflare Worker。仅在需要交互或个性化的地方添加 JavaScript 「Islands」 ↗。

Astro 也与框架无关，通过官方集成 ↗支持所有主流 UI 框架，包括 React、Preact、Svelte、Vue、SolidJS。

在 Workers 上部署新的 Astro 项目

  1. 使用 create-cloudflare CLI (C3) 创建新项目。

    npm create cloudflare@latest -- my-astro-app --framework=astro

    幕后发生了什么？

    运行此命令时，C3 会创建新的项目目录，启动 Astro 官方搭建工具 ↗，并为 Cloudflare 配置项目。随后会提供立即将应用部署到 Cloudflare 的选项。

  2. 在本地开发。

    创建项目后，在项目目录中运行以下命令以启动本地开发服务器。

    npm run dev

  3. 部署项目。

    你可以从本地机器或任何 CI/CD 系统（包括 Workers Builds）将项目部署到 *.workers.dev 子域或自定义域名。使用以下命令进行构建和部署。若使用 CI 服务，请相应更新你的「deploy command」。

    npm run deploy

在 Workers 上部署现有 Astro 项目

AstroDetected
Generated configuration
wrangler.jsonc
main:dist/_worker.js/index.js
wrangler.jsonc
assets:directory: ./dist, binding: ASSETS
wrangler.jsonc
compatibility_flags:nodejs_compat
wrangler.jsonc
observability:enabled: true
astro.config.mjs
adapter:@astrojs/cloudflare
WorkersDeployed
Wrangler handles configuration automatically

手动配置

若希望手动配置项目，请按以下步骤操作。

若为静态站点

若 Astro 项目完全预渲染，请按以下步骤操作：

  1. 添加 Wrangler 配置文件

    在项目根目录创建 Wrangler 配置文件，内容如下：

    {
	"name": "my-astro-app",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"assets": {
		"directory": "./dist"
	}
}
    name = "my-astro-app"
# Set this to today's date
compatibility_date = "2026-08-17"

[assets]
directory = "./dist"

    此配置的作用是什么？

    此配置的关键部分是 assets 字段，它告诉 Wrangler 静态资源的位置。此处我们让 Wrangler 在 ./dist 目录中查找。若资源位于其他目录，请相应更新 directory 值。 阅读其他资源配置选项。

    还要注意此配置中没有 main 字段——因为你仅提供静态资源，按需渲染/SSR 不需要 Worker 代码。

  2. 构建并部署项目

    你可以从本地机器或任何 CI/CD 系统（包括 Workers Builds）将项目部署到 *.workers.dev 子域或自定义域名。使用以下命令进行构建和部署。若使用 CI 服务，请相应更新你的「deploy command」。

    npx astro build
    npx wrangler@latest deploy

若站点使用按需渲染

若 Astro 项目使用按需渲染（也称为 SSR） ↗，请按以下步骤操作：

  1. 安装 Astro Cloudflare 适配器

    npx astro add cloudflare

    幕后发生了什么？

    此命令会安装 Cloudflare 适配器，并一步完成对 astro.config.mjs 文件的相应修改。默认情况下，这会将构建输出配置设为 output: 'server'，即默认对所有页面进行服务端渲染。若有某些页面不需要按需渲染/SSR，例如隐私政策等静态页面，应为该页面或路由设置 export const prerender = true 以预渲染。你可以在 Astro 文档 ↗中阅读更多适配器配置选项。

  2. 添加 .assetsignore 文件 在 public/ 文件夹中创建 .assetsignore 文件，并添加以下行：

    .assetsignoretxt
    _worker.js
_routes.json

  3. 添加 Wrangler 配置文件

    在项目根目录创建 Wrangler 配置文件，内容如下：

    {
	"name": "my-astro-app",
	"main": "./dist/_worker.js/index.js",
	// Update to today's date
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"compatibility_flags": ["nodejs_compat"],
	"assets": {
		"binding": "ASSETS",
		"directory": "./dist"
	},
	"observability": {
		"enabled": true
	}
}
    name = "my-astro-app"
main = "./dist/_worker.js/index.js"
# Set this to today's date
compatibility_date = "2026-08-17"
compatibility_flags = [ "nodejs_compat" ]

[assets]
binding = "ASSETS"
directory = "./dist"

[observability]
enabled = true

    此配置的作用是什么？

    此配置的关键部分包括：

    • main 指向 Worker 脚本的入口点。这由 Astro 适配器生成，用于驱动服务端渲染页面。
    • assets.directory 告诉 Wrangler 静态资源的位置。此处我们让 Wrangler 在 ./dist 目录中查找。若资源位于其他目录，请相应更新 directory 值。

    阅读更多 Wrangler 配置选项和资源配置选项。

  4. 构建并部署项目

    你可以从本地机器或任何 CI/CD 系统（包括 Workers Builds）将项目部署到 *.workers.dev 子域或自定义域名。使用以下命令进行构建和部署。若使用 CI 服务，请相应更新你的「deploy command」。

    npx astro build
    npx wrangler@latest deploy

绑定（binding）

通过绑定（binding），Astro 应用可与 Cloudflare Developer Platform 完全集成，从而访问计算、存储、AI 等能力。请参阅绑定（binding）概览，了解可用功能及配置方式。

Astro 文档 ↗说明了如何在 locals 中访问它们。

Sessions

Astro 的 Sessions API ↗ 允许你在请求之间存储用户数据，例如用户偏好、购物车或身份验证凭据。使用 Cloudflare 适配器时，Astro 会自动为会话存储配置 Workers KV。

部署时 Wrangler 会自动预置名为 SESSION 的 KV 命名空间，因此无需手动设置。

---
export const prerender = false;
const cart = await Astro.session?.get("cart");
---

<a href="/checkout">{cart?.length ?? 0} items</a>

若希望使用不同的绑定（binding）名称，可通过 sessionKVBindingName ↗ 适配器选项自定义 KV 绑定（binding）名称。

自定义 404 页面

要为 Astro 站点提供自定义 404 页面，请在 Wrangler 配置中添加 not_found_handling：

{
	"assets": {
		"directory": "./dist",
		"not_found_handling": "404-page"
	}
}
[assets]
directory = "./dist"
not_found_handling = "404-page"

这会让 Cloudflare 在找不到路由时提供自定义 404 页面（例如 src/pages/404.astro）。阅读更多关于静态资源路由行为的信息。

Astro 的构建配置

Astro Cloudflare 适配器将构建输出配置设为 output: 'server'，即所有页面都在 Cloudflare Worker 中按需渲染。若有某些页面不需要按需渲染/SSR，例如隐私政策等静态页面，应为该页面或路由设置 export const prerender = true 以预渲染。你可以在 Astro 文档 ↗中阅读更多关于按需渲染的内容。

若希望将 Astro 用作静态站点生成器，则不需要 Astro Cloudflare 适配器。Astro 默认会在构建时预渲染所有页面，你可以直接上传这些静态资源由 Cloudflare 提供。

Node.js 要求

Astro 5.x 需要 Node.js 18.17.1 或更高版本。Astro 6（当前为 Beta）需要 Node.js 22 或更高版本。若使用 Workers Builds，请确保构建环境满足这些要求。

这篇文档对您有帮助吗？