Skip to content

i18n(zh-cn): Update deploy/cloudflare.mdx #13629

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yanthomasdev merged 2 commits into from
Apr 1, 2026
Merged

i18n(zh-cn): Update deploy/cloudflare.mdx #13629

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d3c4aab
i18n(zh-cn): Update `deploy/cloudflare.mdx`
liruifengv Mar 31, 2026
d0a2b2e
Merge branch 'main' into update-0331-03
yanthomasdev Apr 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 3 additions & 148 deletions src/content/docs/zh-cn/guides/deploy/cloudflare.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,7 @@ import { Steps } from '@astrojs/starlight/components';
import StaticSsrTabs from '~/components/tabs/StaticSsrTabs.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

你可以通过 [Cloudflare Workers](https://developers.cloudflare.com/workers/static-assets/) 和 [Cloudflare Pages](https://pages.cloudflare.com/) 来部署全栈应用，包括前端的静态资源和后端的 API，以及按需渲染站点。

本指南包含：

- [如何部署至 Cloudflare Workers](#cloudflare-workers)
- [如何部署至 Cloudflare Pages](#cloudflare-pages)
你可以通过 [Cloudflare Workers](https://developers.cloudflare.com/workers/static-assets/) 来部署全栈应用，包括前端的静态资源和后端的 API，以及按需渲染站点。

:::note

Expand Down Expand Up @@ -126,14 +121,14 @@ Cloudflare 更建议为新项目使用 Cloudflare Workers。对于现有的、

### 如何使用 CI/CD 进行部署

你可以使用一个 CI/CD 系统，例如 [Workers Builds (BETA)](https://developers.cloudflare.com/workers/ci-cd/builds/) 来通过推送，自动化构建并部署你的网站。
你可以使用一个 CI/CD 系统，例如 [Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/) 来通过推送，自动化构建并部署你的网站。

假设你正在使用 Workers Builds：

<Steps>
1. 与上文中如何使用 Wrangler 进行部署的步骤 1-3 相同。

2. 登录至 [Cloudflare dashboard](https://dash.cloudflare.com/) 并导航至 `Workers & Pages` 页面。选择 `Create`（创建）。
2. 登录至 [Cloudflare dashboard](https://dash.cloudflare.com/) 并导航至 `Compute > Workers & Pages` 页面。选择 `Create application`（创建应用）。

3. 在 `Import a repository`（导入仓库）选项下，选择一个 Git 账号，然后选择包含你 Astro 项目的仓库。

Expand All @@ -144,144 +139,6 @@ Cloudflare 更建议为新项目使用 Cloudflare Workers。对于现有的、
5. 点击 `Save and Deploy`（保存并部署）。你现在可以在它提供的 `workers.dev` 子域名下，预览 Worker 部署的结果了。
</Steps>

## Cloudflare Pages

### 如何使用 Wrangler 进行部署

<Steps>
1. 安装 [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/)。

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npm install wrangler@latest --save-dev
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm add wrangler@latest --save-dev
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn add wrangler@latest --dev
```
</Fragment>
</PackageManagerTabs>

2. 如果你的站点使用了按需渲染，安装 [`@astrojs/cloudflare` 适配器](/zh-cn/guides/integrations-guide/cloudflare/)。

该步骤将会安装适配器，并对你的 `astro.config.mjs` 文件进行适当的调整。

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npx astro add cloudflare
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro add cloudflare
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn astro add cloudflare
```
</Fragment>
</PackageManagerTabs>

3. 创建一个 [Wrangler 配置项文件](https://developers.cloudflare.com/workers/wrangler/configuration/)。

由于 Cloudflare 建议新项目使用 Workers 而不是 Pages，`astro add cloudflare` 命令会创建 `wrangler.jsonc` 和 `public/.assetsignore` 文件，这些是 Workers 项目特有的。你需要删除 `public/.assetsignore` 文件并修改你的 `wrangler.jsonc` 文件。如果你没有使用适配器，则需要自行创建。

确保你的 `wrangler.jsonc` 文件结构如下：

<StaticSsrTabs>
<Fragment slot="static">
```jsonc title="wrangler.jsonc"
{
"name": "my-astro-app",
"compatibility_date": "YYYY-MM-DD", // 更新为你部署当天的日期
"pages_build_output_dir": "./dist"
}
```
</Fragment>
<Fragment slot="ssr">
```jsonc title="wrangler.jsonc"
{
"name": "my-astro-app",
"compatibility_date": "YYYY-MM-DD", // 更新为你部署当天的日期
"compatibility_flags": [
"nodejs_compat",
"disable_nodejs_process_v2"
],
"pages_build_output_dir": "./dist"
}
```
</Fragment>
</StaticSsrTabs>

<ReadMore>阅读更多有关 [Astro 中的按需渲染](/zh-cn/guides/on-demand-rendering/) 的内容。</ReadMore>

3. 使用 Wrangler 对你的项目进行本地预览。

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npx astro build && wrangler pages dev ./dist
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro build && wrangler pages dev ./dist
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn astro build && wrangler pages dev ./dist
```
</Fragment>
</PackageManagerTabs>

4. 使用 `npx wrangler deploy` 命令进行部署。

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npx astro build && wrangler pages deploy ./dist
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro build && wrangler pages deploy ./dist
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn astro build && wrangler pages deploy ./dist
```
</Fragment>
</PackageManagerTabs>
</Steps>

在你的资源上传之后，Wrangler 将会提供一个预览 URL 用以让你检视自己的网站。

### 如何使用 CI/CD 部署站点

<Steps>
1. 推送代码至 Git 仓库（例如：GitHub、GitLab）。

2. 登录至 [Cloudflare dashboard](https://dash.cloudflare.com/) 并导航至 **Compute (Workers) > Workers & Pages**。选择 **Create**（创建）并选择 **Pages**（页面）标签页。连接至你的 Git 仓库。

3. 配置项目：
- **Framework preset（框架预设）**：`Astro`
- **Build command（构建命令）**：`npm run build`
- **Build output directory（构建输出目录）**：`dist`

4. 点击 **Save and Deploy（保存并部署）** 按钮。
</Steps>

## 故障排除

### 404 行为
Expand All @@ -297,8 +154,6 @@ Cloudflare 更建议为新项目使用 Cloudflare Workers。对于现有的、
}
```

对于 Pages 项目，如果你包含了自定义 404 页面，它会默认被使用。否则，Pages 将默认使用 [Cloudflare 的单页应用渲染行为](https://developers.cloudflare.com/pages/configuration/serving-pages/#single-page-application-spa-rendering)，重定向到主页而不是显示 404 页面。

### 客户端 hydration

由于 Cloudflare 的 Auto Minify（自动压缩）功能，客户端 Hydration 可能会失败。如果你在控制台中看到 `Hydration completed but contains mismatches`，请确保在 Cloudflare 设置中禁用 Auto Minify。
Expand Down
Loading