将你的 Astro 网站部署到 Cloudflare

你可以将全栈应用（包括前端静态资源和后端 API）以及按需渲染的网站部署到 Cloudflare Workers 和 Cloudflare Pages。

¥You can deploy full-stack applications, including front-end static assets and back-end APIs, as well as on-demand rendered sites, to both Cloudflare Workers and Cloudflare Pages.

本指南包括：

¥This guide includes:

• 如何部署到 Cloudflare Workers

• 如何部署到 Cloudflare Pages

Note

Cloudflare recommends using Cloudflare Workers for new projects. For existing Pages projects, refer to Cloudflare’s migration guide and compatibility matrix.

Read more about using the Cloudflare runtime in your Astro project.

先决条件

¥Prerequisites

首先，你将需要：

¥To get started, you will need:

• Cloudflare 账户。如果你还没有，你可以在此过程中创建一个免费的 Cloudflare 账户。

Cloudflare Workers

如何使用 Wrangler 部署

¥How to deploy with Wrangler

1. Install Wrangler CLI.

   npm install wrangler@latest --save-dev

2. If your site uses on-demand rendering, install the @astrojs/cloudflare adapter.

   This will install the adapter and make the appropriate changes to your astro.config.mjs file in one step.

   npm

   npx astro add cloudflare

   pnpm

   pnpm astro add cloudflare

   Yarn

   yarn astro add cloudflare

   Read more about on-demand rendering in Astro.

3. Create a Wrangler configuration file.

   Running astro add cloudflare will create this for you; if you are not using the adapter, you’ll need to create it yourself.

   静止的

   wrangler.jsonc

   {
     "name": "my-astro-app",
     "compatibility_date": "YYYY-MM-DD", // Update to the day you deploy
     "assets": {
       "directory": "./dist",
     }
   }

   按需配置

   wrangler.jsonc

   {
     "main": "dist/_worker.js/index.js",
     "name": "my-astro-app",
     "compatibility_date": "YYYY-MM-DD", // Update to the day you deploy
     "compatibility_flags": [
       "nodejs_compat",
       "global_fetch_strictly_public"
     ],
     "assets": {
       "binding": "ASSETS",
       "directory": "./dist"
     },
     "observability": {
       "enabled": true
     }
   }

4. Preview your project locally with Wrangler.

   npx astro build && npx wrangler dev

5. Deploy using npx wrangler deploy.

   npx astro build && npx wrangler deploy

上传资源后，Wrangler 将为你提供一个预览 URL 以检查你的网站。

¥After your assets are uploaded, Wrangler will give you a preview URL to inspect your site.

Read more about using Cloudflare runtime APIs such as bindings.

如何使用 CI/CD 部署

¥How to deploy with CI/CD

你还可以使用 CI/CD 系统（例如 Workers 构建（BETA 版））在推送时自动构建和部署你的网站。

¥You can also use a CI/CD system such as Workers Builds (BETA) to automatically build and deploy your site on push.

如果你使用的是 Workers Builds：

¥If you’re using Workers Builds:

1. Follow Steps 1-3 from the Wrangler section above.

2. Log in to the Cloudflare dashboard and navigate to Workers & Pages. Select Create.

3. Under Import a repository, select a Git account and then the repository containing your Astro project.

4. Configure your project with:

   • Build command: npx astro build
   • Deploy command: npx wrangler deploy

5. Click Save and Deploy. You can now preview your Worker at its provided workers.dev subdomain.

Cloudflare Pages

如何使用 Wrangler 部署

¥How to deploy with Wrangler

1. Install Wrangler CLI.

   npm

   npm install wrangler@latest --save-dev

   pnpm

   pnpm add wrangler@latest --save-dev

   Yarn

   yarn add wrangler@latest --dev

2. If your site uses on-demand rendering, install the @astrojs/cloudflare adapter.

   This will install the adapter and make the appropriate changes to your astro.config.mjs file in one step.

   npm

   npx astro add cloudflare

   pnpm

   pnpm astro add cloudflare

   Yarn

   yarn astro add cloudflare

3. Create a Wrangler configuration file.

   Because Cloudflare recommends new projects use Workers instead of Pages, the astro add cloudflare command creates a wrangler.jsonc and public/.assetsignore file, which are specific to Workers projects. You will need to delete the public/.assetsignore file and change your wrangler.jsonc file. If you are not using the adapter you’ll need to create it yourself.

   Ensure your wrangler.jsonc file is structured like this:

   静止的

   wrangler.jsonc

   {
     "name": "my-astro-app",
     "compatibility_date": "YYYY-MM-DD", // Update to the day you deploy
     "pages_build_output_dir": "./dist"
   }

   按需配置

   wrangler.jsonc

   {
     "name": "my-astro-app",
     "compatibility_date": "YYYY-MM-DD", // Update to the day you deploy
     "compatibility_flags": [
       "nodejs_compat",
       "disable_nodejs_process_v2"
     ],
     "pages_build_output_dir": "./dist"
   }

   Read more about on-demand rendering in Astro.

4. Preview your project locally with Wrangler.

   npm

   npx astro build && wrangler pages dev ./dist

   pnpm

   pnpm astro build && wrangler pages dev ./dist

   Yarn

   yarn astro build && wrangler pages dev ./dist

5. Deploy using npx wrangler deploy.

   npm

   npx astro build && wrangler pages deploy ./dist

   pnpm

   pnpm astro build && wrangler pages deploy ./dist

   Yarn

   yarn astro build && wrangler pages deploy ./dist

上传资源后，Wrangler 将为你提供一个预览 URL 以检查你的网站。

¥After your assets are uploaded, Wrangler will give you a preview URL to inspect your site.

如何使用 CI/CD 部署网站

¥How to deploy a site with CI/CD

1. Push your code to your git repository (e.g. GitHub, GitLab).

2. Log in to the Cloudflare dashboard and navigate to Compute (Workers) > Workers & Pages. Select Create and then select the Pages tab. Connect your git repository.

3. Configure your project with:

   • Framework preset: Astro
   • Build command: npm run build
   • Build output directory: dist

4. Click the Save and Deploy button.

故障排除

¥Troubleshooting

404 错误行为

¥404 behavior

对于 Workers 项目，如果你想要提供自定义 404 页面，则需要设置 not_found_handling。你可以在 Cloudflare 文档的 路由行为部分 部分了解更多信息。

¥For Workers projects, you will need to set not_found_handling if you want to serve a custom 404 page. You can read more about this in the Routing behavior section of Cloudflare’s documentation.

wrangler.jsonc

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

对于 Pages 项目，如果你包含自定义 404 页面，则默认情况下会显示该页面。否则，页面将默认使用 Cloudflare 单页应用渲染行为 并重定向到主页，而不是显示 404 页面。

¥For Pages projects, if you include a custom 404 page, it will be served by default. Otherwise, Pages will default to Cloudflare’s single-page application rendering behavior and redirect to the home page instead of showing a 404 page.

客户端水合

¥Client-side hydration

由于 Cloudflare 的自动缩小设置，客户端水合作用可能会失败。如果你在控制台中看到 Hydration completed but contains mismatches，请确保在 Cloudflare 设置下禁用 Auto Minify。

¥Client-side hydration may fail as a result of Cloudflare’s Auto Minify setting. If you see Hydration completed but contains mismatches in the console, make sure to disable Auto Minify under Cloudflare settings.

Node.js 运行时 API

¥Node.js runtime APIs

如果你正在构建使用 Cloudflare 适配器 进行按需渲染的项目，并且服务器无法构建并显示错误消息（如 [Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node.）：

¥If you are building a project that is using on-demand rendering with the Cloudflare adapter and the server fails to build with an error message such as [Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node.:

• 这意味着你在服务器端环境中使用的包或导入与 Cloudflare 运行时 API 不兼容。

• 如果你直接导入 Node.js 运行时 API，请参阅 Astro 文档中有关 Cloudflare 的 Node.js 兼容性 的更多步骤以了解如何解决此问题。

• 如果你导入的包会导入 Node.js 运行时 API，请与包的作者核实他们是否支持 node:* 导入语法。如果没有，你可能需要寻找替代包。

更多部署指南

• 

  AWS

• 

  通过 Flightcontrol 使用 AWS

• 

  通过 SST 使用 AWS

• 

  Azion

• 

  Buddy

• 

  Cleavr

• 

  Clever Cloud

• 

  Cloudflare

• 

  CloudRay

• 

  Deno Deploy

• 

  DeployHQ

• 

  Firebase

• 

  Fleek

• 

  Fly.io

• 

  GitHub Pages

• 

  GitLab Pages

• 

  Google Cloud

• 

  Heroku

• 

  Juno

• 

  Kinsta

• 

  Microsoft Azure

• 

  Netlify

• 

  Railway

• 

  Render

• 

  Seenode

• 

  Stormkit

• 

  Surge

• 

  Vercel

• 

  Zeabur

• 

  Zephyr Cloud

• 

  Zerops