Astro

Astro ↗ 是用于构建快速、以内容为中心网站的一体化 Web 框架。默认情况下，Astro 构建的网站不包含 JavaScript 运行时代码。

请参阅 Astro 文档 ↗ 了解更多 Astro 信息或获取 Astro 项目帮助。

在本指南中，你将创建新的 Astro 应用并使用 Cloudflare Pages 部署。

要使用 create-cloudflare 创建新的 Astro 项目，请运行以下命令：

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

yarn create cloudflare my-astro-app --framework=astro --platform=pages

pnpm create cloudflare@latest my-astro-app --framework=astro --platform=pages

Astro 将询问：

1. 要设置的项目类型。你的回答不会影响本教程的其余部分。选择适合项目的选项。

2. 是否要初始化 Git 仓库。建议选择 No 并遵循本指南下方的 Git 说明。若选择 Yes，请勿严格遵循下方 Git 说明，而应根据需要调整。

create-cloudflare 随后将安装依赖，包括 Wrangler CLI 和 @astrojs/cloudflare 适配器，并询问设置问题。

你可以使用 @astrojs/cloudflare 适配器 ↗ 将 Astro 服务端渲染 (SSR) 站点部署到 Cloudflare Pages。SSR 站点在 Pages Functions 上渲染，支持动态功能和自定义。

通过运行以下命令将 @astrojs/cloudflare 适配器 ↗ 添加到项目的 package.json：

npm run astro add cloudflare

所有框架指南都假定你已具备 Git ↗ 的基础知识。如果你是 Git 新手，请参阅这份精简 Git 手册 ↗，了解如何在本地设置 Git。

如果你使用 SSH 克隆，则必须在每台用于向 GitHub 推送或拉取的计算机上生成 SSH 密钥 ↗。

更多信息请参阅 GitHub 文档 ↗和 Git 文档 ↗。

访问 repo.new ↗ 创建新的 GitHub 仓库。创建新仓库后，进入新创建的项目目录，在终端中运行以下命令，准备并将本地应用推送到 GitHub：

git init
git remote add origin https://github.com/<your-gh-username>/<repository-name>
git add .
git commit -m "Initial commit"
git branch -M main
git push -u origin main

如果你使用 create-cloudflare(C3) ↗ 创建新的 Astro 项目，C3 将安装项目所需的所有依赖，并提示你通过 CLI 部署项目。如果部署，你的站点将上线，并会提供部署 URL。

要将站点部署到 Pages：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择 Create application（创建应用程序）。

3. 选择 Pages 选项卡。

4. 选择 Import an existing Git repository（导入现有 Git 仓库）。

5. 选择你创建的新 GitHub 仓库，然后选择 Begin setup（开始设置）。

6. 在 Set up builds and deployments（设置构建和部署） 部分，提供以下信息：

可选：你可以自定义 Project name（项目名称） 字段。它默认为 GitHub 仓库名称，但不必一致。Project name（项目名称） 值将分配为你的 *.pages.dev 子域名。

完成配置后，选择 Save and Deploy（保存并部署）。

你将看到首次部署正在进行。Pages 将安装所有依赖并按指定方式构建项目。

每次推送新提交时，Cloudflare Pages 都会自动重新构建并部署项目。

此外，你还可以使用预览部署，对 pull request 重复构建和部署流程。这样可以在部署到生产环境之前，通过真实 URL 预览项目更改。

本地运行时支持通过 platformProxy 选项配置：

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";

export default defineConfig({
	adapter: cloudflare({
		platformProxy: {
			enabled: true,
		},
	}),
});

绑定（binding） 允许应用与 Cloudflare 开发者产品（如 KV、Durable Objects、R2 和 D1 ↗）交互。

在 Astro 组件和 API 路由中使用绑定，可通过 Astro Middleware ↗ 的 context.locals 访问 Cloudflare 运行时，其中包含 Cloudflare 环境以及为应用设置的任何绑定。

请参阅以下 TypeScript 访问 KV 命名空间的示例。

首先，需要更新 env.d.ts 定义 Cloudflare 运行时和 KV 类型。请确保已通过运行 wrangler types 生成 Cloudflare 运行时类型。

/// <reference types="astro/client" />

type ENV = {
	// replace `MY_KV` with your KV namespace
	MY_KV: KVNamespace;
};

// use a default runtime configuration (advanced mode).
type Runtime = import("@astrojs/cloudflare").Runtime<ENV>;
declare namespace App {
	interface Locals extends Runtime {}
}

然后可以通过以下方式从 API 端点访问 KV：

import type { APIContext } from "astro";

export async function get({ locals }: APIContext) {
	const { MY_KV } = locals.runtime.env;

	return {
		// ...
	};
}

除端点外，还可以直接从 Astro 组件使用绑定：

---
const myKV = Astro.locals.runtime.env.MY_KV;
const value = await myKV.get("key");
---
<div>{value}</div>

有关 Astro Cloudflare 运行时的更多信息，请参阅 Astro 文档中的 Access to the Cloudflare runtime ↗。

完成本指南后，你已成功将 Astro 站点部署到 Cloudflare Pages。要开始使用其他框架，请参阅框架指南列表。