docs / 部署与运维 / deploy

部署指南

构建期用 NUXT_DEPLOY_TARGET 选择部署形态，运行期用环境变量配置数据库与存储。所有形态共用同一套代码与数据库迁移。

目标	命令	产物	适用
`cloudflare-pages`	`pnpm build:pages` → `pnpm deploy`	`dist/`	Cloudflare Pages + D1 + R2（现有站点）
`cloudflare-worker`	`pnpm build:worker` → `wrangler deploy`	`.output/`	Cloudflare Workers（静态资源绑定 `ASSETS`）
`node`	`pnpm build:node` → `pnpm start`	`.output/server/index.mjs`	Linux 服务器、Docker、宝塔
`static-frontend`	`pnpm build:static`	`.output/public/`	前端静态托管（nginx / OSS / COS / R2），后端另行部署
`vercel` / `netlify` / `aws-lambda` / `azure-functions` / `deno-deploy` / `firebase` / `bun` …	`NUXT_DEPLOY_TARGET=vercel pnpm build`	平台约定目录	任意 Nitro 预设，原样透传（短横线换成下划线）

怎么选：

场景	推荐
海外 / 全球访问、零运维、成本最低	Cloudflare Pages + D1 + R2
国内访问为主、已有服务器或宝塔	`node` + nginx + MySQL（宝塔自带）+ OSS / COS
阿里云 FC / 腾讯云 SCF / 腾讯 EdgeOne Pages / 华为云 FunctionGraph	`node` 形态打成自定义运行时或容器镜像（`deploy/Dockerfile`），数据库用云 RDS，附件用 OSS / COS
Vercel / Netlify / AWS / Azure / Deno 等 Serverless	对应 Nitro 预设 + 远程数据库（Turso / Neon / Supabase / PlanetScale / TiDB）+ 对象存储
内容站要极致首屏、后台单独部署	`static-frontend` 放 CDN / OSS，后端任选

1. Cloudflare Pages

沿用现有流程：.cloudflare.env 提供凭据，scripts/deploy.mjs 负责构建、D1 迁移与发布。数据库固定为 D1（NUXT_DB_DRIVER 保持 sqlite），附件用 R2 绑定 BUCKET。

2. Cloudflare Workers

复制 node_modules/nuxtcms/deploy/wrangler.worker.toml.example 为 wrangler.toml，填入 D1 / R2 ID。
pnpm build:worker
wrangler d1 migrations apply <db> --remote
wrangler deploy

Workers 与 Pages 使用相同的 SQLite 迁移文件。若要在 Workers 上使用 PostgreSQL / MySQL，创建 Hyperdrive 并绑定为 HYPERDRIVE，构建时设置 NUXT_DB_DRIVER=pg|mysql。

3. Linux 服务器（含宝塔）

pnpm install
NUXT_DB_DRIVER=mysql pnpm build:node          # 或 sqlite / pg
DATABASE_URL=mysql://user:pass@127.0.0.1:3306/nuxtcms NUXT_DB_AUTO_MIGRATE=1 pnpm start

进程守护：pm2 start deploy/ecosystem.config.cjs --env production。宝塔「网站 → Node 项目」本质是 PM2，把启动文件填 .output/server/index.mjs，环境变量填在项目设置里即可；宝塔自带的 MySQL 直接作为 DATABASE_URL。
反向代理：node_modules/nuxtcms/deploy/nginx-node-proxy.conf.example，/_nuxt/ 由 nginx 直接吐静态文件。
Docker：node_modules/nuxtcms/deploy/Dockerfile，--build-arg NUXT_DB_DRIVER=pg 选择驱动。
附件：本地磁盘（默认 .data/uploads）或 NUXT_STORAGE_DRIVER=oss|cos|s3|r2，详见 README「附件存储」。

4. 前后端分离

前端构建为纯静态 SPA，后端只承担 /api/**。

后端（任选 Pages / Workers / node）运行时增加：

NUXT_CORS_ORIGINS=https://www.example.com      # 允许的前端来源，逗号分隔
NUXT_AUTH_COOKIE_SAME_SITE=none                # 跨域携带登录 Cookie，必须 HTTPS
NUXT_STORAGE_PUBLIC_URL=https://cdn.example.com # 媒体走 CDN，避免相对路径指向前端域

前端构建：

NUXT_PUBLIC_API_BASE=https://api.example.com pnpm build:static
# 上传 .output/public 到 nginx 站点目录或 OSS/COS/R2 静态托管

如果前端与后端同域（nginx 把 /api/ 反代到后端），则不需要 NUXT_PUBLIC_API_BASE 和 CORS，参考 node_modules/nuxtcms/deploy/nginx-static-frontend.conf.example。

限制：SPA 模式没有服务端渲染，SEO 依赖搜索引擎执行 JS；/docs（Nuxt Content）在 SPA 模式下走客户端查询。需要 SEO 的公开站点建议用前三种形态。

5. Serverless 与其他云平台

Serverless 平台没有持久磁盘，所以：

数据库必须是远程的：
- SQLite 方言：Turso（libSQL），DATABASE_URL=libsql://xxx.turso.io + DATABASE_AUTH_TOKEN=...，迁移与 D1 共用；
- PostgreSQL：Neon、Supabase、阿里云 / 腾讯云 RDS，构建时 NUXT_DB_DRIVER=pg；
- MySQL：PlanetScale、TiDB Cloud、云 RDS，构建时 NUXT_DB_DRIVER=mysql。
附件用对象存储：NUXT_STORAGE_DRIVER=s3|oss|cos|r2。
接口缓存自动改用内存（不再写本地文件），构建期预渲染自动关闭。
定时任务：用平台自带的 Cron（Vercel Cron、Netlify Scheduled Functions、EventBridge…）或 deploy/cron-worker 定时请求 POST /api/cron/dispatch。

示例（Vercel）：

NUXT_DEPLOY_TARGET=vercel NUXT_DB_DRIVER=pg pnpm build
# 在 Vercel 项目里配置 DATABASE_URL、NUXT_JWT_SECRET、NUXT_STORAGE_* 等环境变量

阿里云 FC / 腾讯云 SCF：使用 deploy/Dockerfile 构建镜像，以「自定义容器」方式部署，监听端口 3000；数据库与对象存储走内网地址可省流量费。

环境变量速查

变量	阶段	说明
`NUXT_DEPLOY_TARGET`	构建	部署形态
`NUXT_DB_DRIVER`	构建	`sqlite` / `pg` / `mysql`
`DATABASE_URL`	运行	连接串（Cloudflare 上忽略，用绑定）
`DATABASE_AUTH_TOKEN`	运行	远程 libSQL（Turso）令牌
`NUXT_DB_AUTO_MIGRATE`	运行	`1` = 启动时执行迁移（node 形态）
`NUXT_STORAGE_*`	运行	附件存储驱动与凭据
`NUXT_PUBLIC_API_BASE`	构建	静态前端指向的后端地址
`NUXT_CORS_ORIGINS`	运行	后端允许的前端来源
`NUXT_AUTH_COOKIE_SAME_SITE`	运行	跨域时设为 `none`