部署
构建
pnpm build
npm run build
yarn build
bun run build
nuxt build 会预渲染首页与所有能通过链接抓取到的页面,同时生成服务端代码,产物位于 .output/。本地预览:
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 中拦截这条日志:
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 项目,导入仓库后无需改动构建设置:
- 在 Vercel 新建项目并导入 Git 仓库;
- 在 Settings → Environment Variables 中添加上表的环境变量;
- 部署。构建命令为
nuxt build,Nitro 自动使用vercelpreset 输出到.vercel/output/。
使用 vercel preset 时,代理发现的 Markdown 内容协商在边缘完成重写,不经过函数。
Netlify
Netlify 同样能识别 Nuxt 项目,Nitro 在 Netlify 构建环境中自动使用 netlify preset:
- 在 Netlify 导入 Git 仓库,构建命令保持
nuxt build; - 在 Site configuration → Environment variables 中添加环境变量,并把
NODE_VERSION设为符合上述要求的版本,例如24; - 部署。
Cloudflare
部署到 Cloudflare Workers 时使用 cloudflare_module preset,并让 Nitro 生成包含 ASSETS 绑定的 Wrangler 配置:
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 验证响应。
wrangler 配置见 Nuxt 部署文档。Node.js 服务器
在支持上述 Node.js 版本的服务器上运行构建产物:
NUXT_GITHUB_TOKEN=xxx PORT=3000 node .output/server/index.mjs
把 .output/ 整个目录复制到服务器即可,运行时不需要 node_modules。
静态生成
不需要服务端时,可以生成纯静态站点,部署到 GitHub Pages、对象存储等任意静态托管:
pnpm nuxt generate
npx nuxt generate
yarn nuxt generate
bunx 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 更新,需要重新构建。