Nuxt Showcase Template

用于快速搭建展示型网站的 Nuxt 模板，默认集成：

• Nuxt 4
• Nuxt UI（禁用 Google Fonts）
• Nuxt Content（内容统一在 content/ 管理）
• Cloudflare Pages 部署 preset
• server/api 咨询表单接口（Serverless Functions）

模板规范文件

• AI 机器可读规范：template.spec.ai.json
• 人类可读规范：template.spec.human.zh-CN.md
• 兼容规则：ai.rules.json / ai.rules.strict.json
• 前端工程规则：docs/frontend-engineering-rules.md
• 前端工程规则（机器可读）：docs/frontend-engineering-rules.ai.json
• Agent 默认约束：AGENTS.md

技术栈版本（创建时）

• nuxt: 4.4.2
• @nuxt/ui: 4.5.1
• @nuxt/content: 3.12.0

快速开始

pnpm install
# Windows PowerShell:
Copy-Item .env.example .env
# macOS/Linux:
# cp .env.example .env
pnpm dev

访问 http://localhost:3000。

项目结构

app/
  assets/css/main.css         # 全局样式与设计变量
  components/ConsultationForm.vue
  components/ContentPage.vue   # 内容驱动页面主体
  pages/index.vue             # 首页
  pages/[...slug].vue         # 其余内容页
content/
  *.md                        # 所有展示页面内容
server/
  api/contact.post.ts         # 咨询表单 API
content.config.ts             # Content schema（Nuxt Studio 可读）
nuxt.config.ts                # 模块、Cloudflare、Studio、Preview 配置

内容管理（Nuxt Content + Nuxt Studio）

1. 所有页面内容编辑在 content/*.md。
2. 页面字段 schema 定义在 content.config.ts。
3. 预览模式：
   • NUXT_CONTENT_PREVIEW_ENABLED=true|false（默认建议 false，需要时再开启）

字体策略（适配国内网络）

• 已在 nuxt.config.ts 设置 ui.fonts = false，禁用 @nuxt/fonts 自动远程字体加载。
• 在 app/assets/css/main.css 中配置系统字体栈和本地优先回退。

咨询表单工作流

• 前端表单组件：app/components/ConsultationForm.vue
• 服务端处理：server/api/contact.post.ts
• 数据访问封装：server/db/client.ts + server/db/repositories/contact-inquiry.repository.ts（Drizzle ORM + D1）
• 接口地址：POST /api/contact
• 可选 Webhook 转发：
  • CONTACT_WEBHOOK_URL
  • CONTACT_WEBHOOK_SECRET

Drizzle ORM 与 D1 迁移

• Drizzle 配置：drizzle.config.ts
• Schema 文件：server/db/schema.ts
• 迁移目录：migrations/

生成迁移：

pnpm db:generate

应用迁移到本地 D1（开发）：

pnpm db:migrate:local

应用迁移到远端 D1（Cloudflare）：

pnpm db:migrate:remote

Cloudflare Pages 部署

1) 在 Cloudflare Pages 配置构建

• Build command: pnpm build:pages
• Build output directory: dist

2) 推荐环境变量

• NUXT_CONTENT_PREVIEW_ENABLED=false
• CLOUDFLARE_ACCOUNT_ID=<你的账号ID>
• CLOUDFLARE_PAGES_PROJECT_NAME=<你的Pages项目名>
• CLOUDFLARE_D1_DATABASE_NAME=<你的D1数据库名>
• CLOUDFLARE_D1_DATABASE_ID=<你的D1数据库ID>
• CONTACT_WEBHOOK_URL（可选）
• CONTACT_WEBHOOK_SECRET（可选）

3) 初始化 D1（首次）

wrangler d1 create nuxt-content-db

把返回的 database_id 写入 .env 的 CLOUDFLARE_D1_DATABASE_ID。

4) 生成本地 Cloudflare 配置（不入库）

pnpm cf:sync

会基于 .env 生成本地 wrangler.toml（已在 .gitignore 中忽略，不会被提交）。

5) 本地预览 Cloudflare Pages 输出

pnpm build:pages
pnpm pages:dev

6) CLI 部署（可选）

pnpm build:pages
pnpm pages:deploy

兼容性说明

@nuxt/content@3.12.0 在部分环境会缺失一个 preview 依赖文件。模板已在 postinstall 中加入补丁脚本 scripts/patch-nuxt-content.mjs，用于自动修复该问题。

常用命令

pnpm install
pnpm cf:sync
pnpm dev
pnpm build
pnpm generate
pnpm preview
pnpm build:pages
pnpm pages:dev
pnpm pages:deploy
pnpm db:generate
pnpm db:migrate:local
pnpm db:migrate:remote
pnpm test
pnpm test:unit
pnpm test:unit:watch
pnpm test:e2e
pnpm test:e2e:headed
pnpm test:e2e:ui
pnpm test:e2e:install
pnpm validate:template-spec

命令用途说明

• pnpm install：安装项目依赖。
• pnpm cf:sync：根据 .env 生成本地 wrangler.toml（Cloudflare Pages/D1 配置）。
• pnpm dev：启动 Nuxt 本地开发服务器。
• pnpm build：构建生产版本（Nuxt + Nitro）。
• pnpm generate：生成静态站点产物。
• pnpm preview：本地预览构建结果。
• pnpm build:pages：按 Cloudflare Pages 流程构建（先 cf:sync 再 build）。
• pnpm pages:dev：用 Wrangler 本地模拟 Pages 运行 dist。
• pnpm pages:deploy：通过 Wrangler 部署 dist 到 Cloudflare Pages。
• pnpm db:generate：根据 server/db/schema.ts 生成 Drizzle 迁移文件到 migrations/。
• pnpm db:migrate:local：把迁移应用到本地 D1。
• pnpm db:migrate:remote：把迁移应用到 Cloudflare 远端 D1。
• pnpm test：执行完整测试（单测 + E2E）。
• pnpm test:unit：执行 Vitest 单元测试。
• pnpm test:unit:watch：启动 Vitest 监听模式。
• pnpm test:e2e：执行 Playwright E2E（默认自动拉起本地 dev）。
• pnpm test:e2e:headed：执行有界面模式 E2E，便于调试。
• pnpm test:e2e:ui：打开 Playwright UI 测试面板。
• pnpm test:e2e:install：首次安装 Playwright 浏览器。
• pnpm validate:template-spec：校验模板规范文件与项目配置是否一致（适合 CI）。
• pnpm postinstall：安装后自动执行补丁与 Nuxt prepare（通常无需手动执行）。

自动化测试

Vitest（单元测试）

pnpm test:unit
pnpm test:unit:watch

Playwright（E2E）

首次安装浏览器（仅需一次）：

pnpm test:e2e:install

本地回归（自动拉起 pnpm dev --port 3001）：

pnpm test:e2e

对已部署环境回归（不启动本地 dev）：

E2E_BASE_URL=https://your-preview.pages.dev pnpm test:e2e