---
title: "配置"
description: "defineConfig 和 Nimbus 集成接受的所有选项。"
---
> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# 配置
Nimbus 在 `astro.config.ts` 中进行配置。`defineConfig`（重新导出为 `defineNimbusConfig`）为站点配置提供类型支持；`nimbus()` 集成接收该配置以及构建时选项。
```ts title="astro.config.ts"
import { defineConfig } from "astro/config";
import nimbus, {
defineConfig as defineNimbusConfig,
} from "@cloudflare/nimbus-docs";
const config = defineNimbusConfig({
site: "https://docs.example.com",
title: "Acme",
description: "Build with Acme.",
github: "https://github.com/acme/docs",
editPattern: "https://github.com/acme/docs/edit/main/{path}",
sidebar: { items: [/* … */] },
});
export default defineConfig({
integrations: [nimbus(config, {/* options */})],
});
```
站点配置
| 字段 | 类型 | 说明 |
| -------------------------------- | ----------------- | ---------------------------------------------------------------------------- |
| `site` | string | **必填。** 规范站点 URL。桥接到 Astro 的 `site`。 |
| `title` | string | **必填。** 站点标题及元数据回退值。 |
| `description` | string | 默认 meta 描述。 |
| `locale` | string | 文档语言（如 `"en"`）。 |
| `homeLabel` | string | 「首页」面包屑的标签。 |
| `github` | string \| null | 头部链接的仓库 URL；`null` 则隐藏。 |
| `editPattern` | string \| null | 编辑链接模式；`{path}` 为页面路径。 |
| `socialImage` / `socialImageAlt` | string | OG 回退图片和替代文本。参见 [元数据和 SEO](/ai/metadata-and-seo)。 |
| `head` | array | 站点级 `` 元素。 |
| `sidebar` | object | 侧边栏配置——参见 [侧边栏](/navigation/sidebar)。 |
| `features` | object | `sidebar` / `tableOfContents` 开关。参见 [布局](/styling/layouts)。 |
| `search` | object \| `false` | 搜索后端。参见 [搜索](/navigation/search)。 |
| `versions` | object | 版本清单——每个版本都是独立的内容集合。 |
| `rendering` | object | 规范内容集合路由的构建或请求渲染策略。 |
渲染策略
`rendering` 控制规范内容集合路由：Nimbus 用于文档、API 参考和其他注册集合的通配路由。它不会改变 `src/pages/` 下的自定义文件。
| 模式 | 行为 | 部署要求 |
| --- | --- | --- |
| `"build"` | 在 `astro build` 期间预渲染路由。这是默认值。 | 任何静态或服务端部署。 |
| `"request"` | 在访客请求时渲染路由。 | Astro 服务端输出，配合 Nimbus 支持的适配器。 |
省略 `rendering` 等同于 `rendering: { default: "build" }`。
启用请求渲染
请求渲染需要三个条件：Astro 配置中的 `output: "server"`、Nimbus 支持的适配器，以及 Nimbus 配置中至少一个集合设置为 `"request"`。特定提供商的配置如下所列。
当大部分或全部规范集合路由需要按请求渲染时，设置默认值：
```ts
const nimbusConfig = defineNimbusConfig({
// ...
rendering: {
default: "request",
},
});
```
更改输出模式或渲染策略后，请运行生产构建。这是验证所选适配器是否支持 Nimbus 请求渲染的权威检查。
混合构建和请求渲染
`rendering.default` 应用于每个具有规范通配路由的已注册集合。`rendering.collections` 按 Astro 集合名称（而非 URL 或版本）覆盖该模式。
按请求渲染大部分集合，但保持归档集合预渲染：
```ts
rendering: {
default: "request",
collections: {
archived: "build",
},
},
```
或者保持站点静态，但为一个集合启用请求渲染：
```ts
rendering: {
default: "build",
collections: {
api: "request",
},
},
```
每个覆盖必须指定一个具有自身规范通配路由的已注册集合。Nimbus 会对未知集合名称报错，而不是静默忽略。
请求渲染的路由在生产构建期间仍会添加到站点地图和 Pagefind 搜索索引。Nimbus 使用内容源创建这些构建时发现文件；无需额外的站点地图或搜索配置。
Cloudflare
Cloudflare 目前是 Nimbus 请求渲染集合路由的支持提供商。创建新站点时选择 **Server** 和 **Cloudflare**。对于现有站点，从项目根目录运行适配器安装程序：
```sh
npx add adapter-cloudflare
pnpm dlx add adapter-cloudflare
yarn dlx add adapter-cloudflare
bunx add adapter-cloudflare
```
安装程序会连接 `@astrojs/cloudflare` 并将 Astro 设置为服务端输出。当 `wrangler.jsonc` 不存在时会创建它，或替换未更改的 Nimbus 静态配置。自定义的 Wrangler 文件和替代的 JSON 或 TOML 配置会被保留，并提供手动操作指引。
当活跃的 Nimbus 配置没有渲染策略时，安装程序会添加 `rendering: { default: "request" }`。现有策略会被保留。如果导入的或模糊的 Nimbus 配置无法安全编辑，安装程序会完成适配器设置并打印生成编码智能体配方的说明。使用以下命令生成该配方：
```sh
npx add adapter-cloudflare --print
pnpm dlx add adapter-cloudflare --print
yarn dlx add adapter-cloudflare --print
bunx add adapter-cloudflare --print
```
将打印的配方传递给你的编码智能体以完成项目特定的配置。
生成的 Astro 配置包含渲染策略、服务端输出和适配器：
```ts title="astro.config.ts"
import cloudflare from "@astrojs/cloudflare";
import { defineConfig } from "astro/config";
import nimbus, {
defineConfig as defineNimbusConfig,
} from "@cloudflare/nimbus-docs";
const nimbusConfig = defineNimbusConfig({
site: "https://docs.example.com",
title: "Acme",
rendering: {
default: "request",
},
});
export default defineConfig({
output: "server",
adapter: cloudflare({ prerenderEnvironment: "node" }),
integrations: [nimbus(nimbusConfig)],
});
```
Cloudflare 部署还需要一个兼容服务端的 `wrangler.jsonc`。设置完成后运行 `pnpm build` 以验证适配器和 Wrangler 配置。
参见 [服务端适配器](/cli#server-adapters) 了解安装程序的行为和安全检查。
集成选项
`nimbus()` 的第二个参数控制构建行为：
| 选项 | 默认值 | 说明 |
| -------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `validateMdx` | `true` | PascalCase 标签验证。`false` 跳过；对象可覆盖路径。参见 [Markdown 和 MDX](/writing/markdown-and-mdx)。 |
| `admonitions` | `true` | 原生 Sätteri MDX 指令 → `