Astro 静态站点生成器

使用 Astro 框架在 Cloudflare 上免费部署多语言静态网站。

前置条件

• - 已安装 Node.js 20+
• Cloudflare 账户（免费）
• Git 仓库（GitHub、GitLab 或 Bitbucket）

快速开始

1. 创建项目

bash
npm create astro@latest my-site -- --template minimal
cd my-site
npm install

2. 配置 Cloudflare

静态站点（推荐大多数用例）

无需适配器。使用默认静态输出：

javascript
// astro.config.mjs
import { defineConfig } from astro/config;

export default defineConfig({
site: https://your-site.pages.dev,
});

SSR/边缘函数（可选）

如果需要服务端渲染或边缘函数：

bash
npm install @astrojs/cloudflare

javascript
// astro.config.mjs
import { defineConfig } from astro/config;
import cloudflare from @astrojs/cloudflare;

export default defineConfig({
output: server,
adapter: cloudflare(),
site: https://your-site.pages.dev,
});

3. 部署到 Cloudflare

Git 集成（推荐）

1. 1. 推送到 GitHub/GitLab
2. Cloudflare 控制台 → Pages → 创建项目 → 连接 Git
3. 配置：

- 构建命令：npm run build - 构建输出目录：dist

直接上传

bash

部署（通过 Cloudflare 控制台或 wrangler 进行身份验证）

npx wrangler pages deploy dist

多语言配置

Astro 配置

javascript
// astro.config.mjs
export default defineConfig({
i18n: {
defaultLocale: en,
locales: [en, es, fr, de],
routing: {
prefixDefaultLocale: false, // /about 而非 /en/about
},
},
});

路由模式：

设置	URL 结构	最佳用途
prefixDefaultLocale: false	/about, /es/about	默认语言在根路径
prefixDefaultLocale: true

/en/about, /es/about | 所有语言带前缀 |

内容结构

src/content/
├── config.ts # 内容集合模式
└── docs/
├── en/
│ ├── index.md
│ └── guide.md
├── es/
│ ├── index.md
│ └── guide.md
└── fr/
├── index.md
└── guide.md

内容集合模式

typescript
// src/content/config.ts
import { defineCollection, z } from astro:content;

const docs = defineCollection({
type: content,
schema: z.object({
title: z.string(),
description: z.string(),
lang: z.enum([en, es, fr, de]),
}),
});

export const collections = { docs };

注意： 添加内容集合后运行 npx astro sync 以生成类型。

语言切换器组件

astro

---

// src/components/LanguageSwitcher.astro
const languages = {
en: English,
es: Español,
fr: Français,
de: Deutsch,
};

const currentPath = Astro.url.pathname;
const currentLang = Astro.currentLocale || en;

---

{Object.entries(languages).map(([code, name]) => (
value={/${code}${currentPath}}
selected={code === currentLang}
>
{name}

))}

文件结构

my-site/
├── astro.config.mjs # Astro 配置
├── package.json
├── public/
│ ├── favicon.svg
│ └── _redirects # Cloudflare 重定向（可选）
├── src/
│ ├── components/
│ │ └── LanguageSwitcher.astro
│ ├── content/
│ │ ├── config.ts
│ │ └── blog/
│ │ ├── en/
│ │ └── es/
│ ├── layouts/
│ │ └── BaseLayout.astro
│ └── pages/
│ ├── index.astro
│ ├── en/
│ │ └── index.astro
│ └── es/
│ └── index.astro

Cloudflare Pages 设置

设置	值
构建命令	npm run build
构建输出目录

dist | | Node 版本 | 20 | | 环境变量 | NODE_VERSION=20 |

自定义域名

Cloudflare 控制台 → Pages → your-site → 自定义域名 → 添加域名

重定向

创建 public/_redirects：

/ /en/ 302
/old-page /new-page 301

命令参考

命令	描述
npm run dev	启动开发服务器
npm run build

构建生产版本 | | npm run preview | 预览生产构建 | | npx astro sync | 生成内容集合类型 | | npx wrangler login | 使用 Cloudflare 进行身份验证 | | npx wrangler pages deploy dist | 部署到 Cloudflare |

使用内容集合的博客

astro

---

// src/pages/blog/[...slug].astro
import { getCollection } from astro:content;

export async function getStaticPaths() {
const posts = await getCollection(blog);
return posts.map(post => ({
params: { slug: post.slug },
props: { post },
}));
}

const { post } = Astro.props;
const { Content } = await post.render();

---

{post.data.title}

故障排除

Cloudflare 构建失败

在 Cloudflare Pages 环境变量中设置 NODE_VERSION=20。

嵌套路由返回 404

javascript
// astro.config.mjs
export default defineConfig({
trailingSlash: always,
});

i18n 不工作

确保：

1. 1. 语言代码与文件夹名称完全匹配
2. 内容文件具有正确的 lang 前置元数据
3. 创建内容集合后运行 npx astro sync

内容集合类型错误

运行 npx astro sync 以生成 TypeScript 类型。

资源

• - Astro 文档
• Cloudflare Pages 文档
• Astro i18n 指南
• Cloudflare 适配器

脚本

脚本	描述
astro-new-post.py	创建多语言博客文章
astro-i18n-check.py

验证翻译覆盖率 |

脚本使用

bash

创建多语言新文章

python scripts/astro-new-post.py --title 我的文章 --langs en,es,fr

带作者和标签创建

python scripts/astro-new-post.py --title 教程 --langs en,es --author John --tags tutorial,astro

检查翻译覆盖率

python scripts/astro-i18n-check.py --langs en,es,fr

检查特定内容目录

python scripts/astro-i18n-check.py --content-dir src/content/blog --langs en,es

输出为 JSON

python scripts/astro-i18n-check.py --langs en,es,fr --json

所有脚本仅使用 Python 标准库（无依赖项）。