---
title: "部署"
description: "把文档站部署到 Vercel、Netlify、Cloudflare 或任意 Node.js 服务器，也可以生成纯静态站点。本页列出构建命令、环境变量、各平台的注意事项，以及静态部署下不可用的功能。"
canonical_url: "https://docs.mhaibaraai.cn/docs/guide/deployment"
---
# 部署

> 把文档站部署到 Vercel、Netlify、Cloudflare 或任意 Node.js 服务器，也可以生成纯静态站点。本页列出构建命令、环境变量、各平台的注意事项，以及静态部署下不可用的功能。

## 构建

```bash [pnpm]
pnpm build
```

```bash [npm]
npm run build
```

```bash [yarn]
yarn build
```

```bash [bun]
bun run build
```

`nuxt build` 会预渲染首页与所有能通过链接抓取到的页面，同时生成服务端代码，产物位于 `.output/`。本地预览：

```bash [terminal]
node .output/server/index.mjs
```

构建与运行都需要 Node.js 22.22.3+（22.x）、24.15.0+（24.x）或 26+：Nuxt Content 使用 Node.js 内置的 `node:sqlite`，无需安装 `better-sqlite3`。

### 检查死链

Layer 设置了 `nitro.prerender.failOnError: false`，预渲染遇到死链时不会中断构建，只在日志中输出 `[request error]`。建议在 CI 中拦截这条日志：

```bash [terminal]
pnpm build 2>&1 | tee build.log
! grep '\[request error\]' build.log
```

## 环境变量

| 变量 | 是否必需 | 说明 |
| --- | --- | --- |
| `NUXT_GITHUB_TOKEN` | 生产环境必需 | GitHub 访问令牌。[`CommitChangelog`](https://docs.mhaibaraai.cn/docs/components/commit-changelog) 与 [`PageLastCommit`](https://docs.mhaibaraai.cn/docs/components/page-last-commit) 没有令牌时不显示内容；版本发布页可以匿名请求，但受 GitHub 每小时 60 次的限制 |
| `AI_API_KEY` | 否 | AI Chat 的总开关，构建时存在即启用 AI Chat，见 [AI Chat](https://docs.mhaibaraai.cn/docs/ai/ai-chat) |
| `AI_BASE_URL` | 否 | OpenAI 兼容端点，如 `https://api.deepseek.com/v1`；留空时通过 Vercel AI Gateway 调用 |
| `NUXT_APP_SECRET` | 使用运行时 OG 图片签名时必需 | 至少 32 个字符的稳定私密值，配置于生产运行环境 |

`AI_API_KEY` 在构建时决定 AI Chat 是否打包进产物，在运行时用于调用模型，所以构建环境与运行环境都要配置。令牌只需要读取公开仓库的权限。

Layer 默认启用 `ogImage.zeroRuntime`，预渲染 OG 图片时不需要配置应用密钥。如果改为运行时渲染并保留 URL 签名，需按 [OG Image v7 迁移指南](https://nuxtseo.com/docs/og-image/migration-guide/v7#move-signing-to-nuxt_app_secret)配置 `NUXT_APP_SECRET`。

## Vercel

Vercel 能识别 Nuxt 项目，导入仓库后无需改动构建设置：

1. 在 Vercel 新建项目并导入 Git 仓库；
2. 在 **Settings → Environment Variables** 中添加上表的环境变量；
3. 部署。构建命令为 `nuxt build`，Nitro 自动使用 `vercel` preset 输出到 `.vercel/output/`。

使用 `vercel` preset 时，[代理发现](https://docs.mhaibaraai.cn/docs/ai/agent-discovery)的 Markdown 内容协商在边缘完成重写，不经过函数。

## Netlify

Netlify 同样能识别 Nuxt 项目，Nitro 在 Netlify 构建环境中自动使用 `netlify` preset：

1. 在 Netlify 导入 Git 仓库，构建命令保持 `nuxt build`；
2. 在 **Site configuration → Environment variables** 中添加环境变量，并把 `NODE_VERSION` 设为符合上述要求的版本，例如 `24`；
3. 部署。

## Cloudflare

部署到 Cloudflare Workers 时使用 `cloudflare_module` preset，并让 Nitro 生成包含 `ASSETS` 绑定的 Wrangler 配置：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  nitro: {
    preset: 'cloudflare_module',
    cloudflare: { deployConfig: true, nodeCompat: true }
  }
})
```

Workers 运行时没有 `node:sqlite`，Nuxt Content 在 Cloudflare preset 下会改用 D1 数据库，并要求绑定名为 `DB`。在 Cloudflare 控制台创建一个 D1 数据库，以 `DB` 绑定到 Worker，再部署。环境变量在 Worker 的 **Settings → Variables and Secrets** 中配置。

启用 MCP Server 时，项目需要安装 `agents`，供 MCP Toolkit 的 Cloudflare 传输使用。

如果预渲染了 HTML 页面，让这些页面的请求先进入 Worker，以便 Nitro 处理 Markdown 内容协商。用同一 URL 分别发送 `Accept: text/html` 和 `Accept: text/markdown` 验证响应。

> [!NOTE]
> 
> Cloudflare 的完整步骤与 
> 
> wrangler
> 
>  配置见 
> 
> Nuxt 部署文档
> 
> 。

## Node.js 服务器

在支持上述 Node.js 版本的服务器上运行构建产物：

```bash [terminal]
NUXT_GITHUB_TOKEN=xxx PORT=3000 node .output/server/index.mjs
```

把 `.output/` 整个目录复制到服务器即可，运行时不需要 `node_modules`。

## 静态生成

不需要服务端时，可以生成纯静态站点，部署到 GitHub Pages、对象存储等任意静态托管：

```bash [pnpm]
pnpm nuxt generate
```

```bash [npm]
npx nuxt generate
```

```bash [yarn]
yarn nuxt generate
```

```bash [bun]
bunx nuxt generate
```

产物位于 `.output/public/`。页面、全文搜索、组件 Props / 示例、`llms.txt`、`sitemap.xml` 与 OG 图片都在构建时生成，静态托管下正常工作。以下功能依赖服务端，静态站点中不可用：

| 功能 | 原因 |
| --- | --- |
| [AI Chat](https://docs.mhaibaraai.cn/docs/ai/ai-chat) | 对话通过 `/api/ai-chat` 实时调用模型 |
| [MCP Server](https://docs.mhaibaraai.cn/docs/ai/mcp) | `/mcp` 是运行时接口 |
| [`CommitChangelog`](https://docs.mhaibaraai.cn/docs/components/commit-changelog)、[`PageLastCommit`](https://docs.mhaibaraai.cn/docs/components/page-last-commit) | 在浏览器中请求 `/api/github/*`，静态站点没有这些接口 |
| Markdown 内容协商 | 根据 `Accept` 请求头返回 Markdown 需要服务端中间件或边缘重写 |

版本发布页的数据在预渲染时获取并写入页面，之后不会随 GitHub 更新，需要重新构建。

## 相关资源

- [Nuxt 部署文档](https://nuxt.com/deploy)
- [Nitro 部署指南](https://nitro.build/deploy)


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
