Cloudflare Nimbus 详细部署教程

项目概述

Nimbus 是 Cloudflare 推出的一个现代化文档站点框架，基于 Astro 构建。它的核心理念是让人类和 AI 代理（agents）都成为一等公民——文档站点不仅对人类读者友好，还能被 AI 代理以原生格式高效读取。

Nimbus 会将完整的 Astro 文档站点脚手架（布局、组件、样式、路由、内容）作为真实文件生成到你的仓库中，你可以从第一次提交开始自由编辑。不可见的底层管道以 npm 包形式发布，而你看到和塑造的一切都归你所有。

核心特性：

特性	说明
自有源码	布局、组件、内容集合、样式和主题令牌全部可编辑
面向代理的文档	每个可发现页面的 Markdown 版本、MDX 源版本、`/llms.txt`、`/llms-full.txt`、JSON-LD、站点地图、robots.txt、每页 OG 图片
阅读器体验	全文搜索、明暗主题、无障碍导航、面包屑、分页、移动端侧边栏
编写护栏	散文和结构 lint、MDX 组件验证器、配置验证
版本化文档	并行版本、alternate 链接、规范链接、自动重定向

技术栈：Astro 7 · Sätteri（基于 Rust 的 Markdown）· Tailwind v4 · 可选 React 19

部署前准备

系统要求

项目	要求
Node.js	18+（推荐 20+）
包管理器	pnpm / npm / yarn / bun
操作系统	Windows / macOS / Linux
网络	需能访问 npm registry

环境检查

1 2	node --version pnpm --version # 如未安装，可运行 npm install -g pnpm

方案一：使用脚手架创建项目（推荐）

这是 Nimbus 的标准使用方式——它会将完整的文档站点脚手架写入你的仓库。

步骤 1：运行脚手架

npx @cloudflare/create-nimbus-docs@latest my-docs
cd my-docs
pnpm install
pnpm dev

步骤 2：打开开发服务器

浏览器访问终端中打印的 URL（通常是 http://localhost:4321）。

步骤 3：编辑内容

编辑 src/ 下的任何文件，页面会自动热重载。你现在已经拥有一个完整的文档站点。

跳过交互式提问

脚手架会询问几个问题（输出模式、部署目标或适配器、包管理器、起始内容或空内容）。使用 --yes 跳过：

1	npx @cloudflare/create-nimbus-docs@latest my-docs --yes

交互式运行时可以选择包管理器；--yes 模式下默认使用 npm，可通过 --package-manager pnpm（或 yarn/bun）指定其他。

常用命令

在你的项目目录内运行以下命令：

命令	功能
`pnpm dev`	开发服务器，支持热重载
`pnpm build`	使用选定的输出模式和适配器构建
`pnpm preview`	预览构建后的站点
`pnpm typecheck`	类型检查（`astro check`）
`pnpm lint:docs`	检查散文和 MDX（添加 `--fix` 自动修复）

部署方式

Nimbus 默认输出静态站点，pnpm build 会生成 dist/ 目录，可以托管在任何地方。

方案 A：部署到 Cloudflare（一等公民支持）

Cloudflare 是 Nimbus 的一等目标平台，默认脚手架已包含 wrangler.jsonc 配置文件。

1 2	pnpm build pnpm run deploy # wrangler deploy 部署到 Cloudflare

方案 B：服务器端输出（按需渲染）

在脚手架阶段选择 Cloudflare server output，可以在请求时渲染规范的内容集合路由。

现有项目添加适配器：

1	pnpm exec nimbus-docs add adapter-cloudflare

将渲染编辑交给编码代理：

1	pnpm exec nimbus-docs add adapter-cloudflare --print \| claude

方案 C：部署到其他静态托管平台

由于 pnpm build 输出标准的 dist/ 目录，你可以将其部署到任何静态托管服务：

平台	部署方式
Netlify	拖拽 `dist/` 目录或连接 Git 仓库
Vercel	导入 Git 仓库，框架预设选 Astro
GitHub Pages	将 `dist/` 推送到 `gh-pages` 分支
任意静态服务器	上传 `dist/` 内容

按需添加组件

从注册表拉取可选的组件、工具和代理交接功能——每个都会作为你拥有的源码文件落入仓库：

1 2	pnpm dlx @cloudflare/nimbus-docs add dialog pnpm dlx @cloudflare/nimbus-docs add 404-page

组件和工具以可编辑文件形式复制进来。功能则会交给你的编码代理读取、适配到你的项目并应用。

项目结构说明

Nimbus 脚手架生成的项目结构如下：

text

my-docs/
├── src/
│   ├── layouts/          # 页面布局（可编辑）
│   ├── components/       # 组件（可编辑）
│   ├── content/          # 内容集合
│   ├── styles/           # 样式和主题令牌
│   └── pages/            # 路由
├── public/               # 静态资源
├── astro.config.mjs      # Astro 配置
├── wrangler.jsonc        # Cloudflare 部署配置（如选择 Cloudflare）
└── package.json

所有布局、组件、样式和路由都是你可以自由编辑的真实文件。

高级功能

交互式图表

Nimbus 提供可选的 React 原语用于交互式图表：

import { Diagram, usePhase, useMeasure } from "@cloudflare/nimbus-docs/react";

export function MyCard() {
  return (
    <Diagram label="My card">
      {/* 你的卡片内容 */}
    </Diagram>
  );
}

安装可见组件：

1	pnpm dlx @cloudflare/nimbus-docs add diagram

通过 Astro 的 client:visible 指令挂载卡片，使 hydration 延迟到图表进入视口时。

版本化文档

Nimbus 支持并行版本，包含 alternate 链接、规范链接和自动重定向——当你需要维护多个版本文档时使用。

Agent 友好特性

每页 Markdown 版本：每个可发现页面都有干净的 Markdown 版本
MDX 源版本：每个可发现的手写页面都有准备的 MDX 源版本
/llms.txt 和 /llms-full.txt：供 LLM 读取的项目上下文
JSON-LD：结构化数据
站点地图和 robots.txt：标准 SEO 支持
每页 OG 图片：社交分享图片

这些面向代理的格式默认发布，而非附加功能。

常见问题排查

问题	解决方案
`npx` 命令失败	检查网络连接，确保 Node.js 版本为 18+
`pnpm install` 报错	尝试 `pnpm store prune` 后重试，或使用 `npm install`
开发服务器无法访问	检查终端输出的端口号（默认 4321），确认端口未被占用
构建失败	运行 `pnpm typecheck` 查看具体类型错误
Cloudflare 部署失败	检查 `wrangler.jsonc` 配置，确保已登录 `wrangler login`
代理交接失败	确认编码代理（如 Claude Code）已正确安装并配置

状态说明

Nimbus 目前处于 pre-1.0（0.x） 阶段，正在快速迭代。你可以用它构建真实站点，但公共接口可能在次要版本之间变化，且存在一些粗糙边缘。请固定版本，并在升级前查看每个包的变更日志。

总结

部署方式	适用场景	难度	推荐度
脚手架 + Cloudflare	大多数用户，追求最佳集成	⭐	⭐⭐⭐⭐⭐
脚手架 + 其他静态托管	已有托管偏好	⭐	⭐⭐⭐⭐
服务器端输出	需要按需渲染	⭐⭐	⭐⭐⭐

对于大多数用户，脚手架创建 + Cloudflare 部署是最简单直接的选择：

# 创建项目
npx @cloudflare/create-nimbus-docs@latest my-docs
cd my-docs
pnpm install

# 本地开发
pnpm dev

# 构建并部署
pnpm build
pnpm run deploy

完成部署后，你的文档站点将同时为人类读者和 AI 代理提供优化的访问体验。所有源码都在你的仓库中，可以自由定制——这正是 Nimbus “你拥有每一个文件” 设计理念的体现。