部署

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

构建

pnpm build

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

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 中拦截这条日志:

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

环境变量

变量是否必需说明
NUXT_GITHUB_TOKEN生产环境必需GitHub 访问令牌。CommitChangelog 与 PageLastCommit 没有令牌时不显示内容;版本发布页可以匿名请求,但受 GitHub 每小时 60 次的限制
AI_API_KEY否AI Chat 的总开关,构建时存在即启用 AI Chat,见 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 迁移指南配置 NUXT_APP_SECRET。

Vercel

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

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

使用 vercel preset 时,代理发现的 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 配置:

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 验证响应。

Cloudflare 的完整步骤与 wrangler 配置见 Nuxt 部署文档。

Node.js 服务器

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

terminal
NUXT_GITHUB_TOKEN=xxx PORT=3000 node .output/server/index.mjs

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

静态生成

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

pnpm nuxt generate

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

功能原因
AI Chat对话通过 /api/ai-chat 实时调用模型
MCP Server/mcp 是运行时接口
CommitChangelog、PageLastCommit在浏览器中请求 /api/github/*,静态站点没有这些接口
Markdown 内容协商根据 Accept 请求头返回 Markdown 需要服务端中间件或边缘重写

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

相关资源

Copyright © 2024 - 2026