内容型独立站：Nuxt Content + Cloudflare Pages

这套模板解决什么问题

内容站的常见困境：用 WordPress 要养服务器、要打补丁；用纯静态生成器又缺服务端能力（重定向、动态 sitemap、按需渲染）。

这套组合的取舍是：内容用 Markdown 管在 git 里，渲染跑在边缘节点上，成本接近零。

写作时改的是 .md 文件，走 git 提交、有历史、能回滚、能 review。部署后每个请求由 Cloudflare Worker 就近响应，没有源站，也就没有服务器要维护。

从零复现

一、起项目

mkdir my-site && cd my-site
pnpm init

根 package.json：

{
  "name": "my-site",
  "private": true,
  "packageManager": "pnpm@8.6.12",
  "scripts": {
    "dev": "pnpm --filter web dev",
    "build": "pnpm --filter web build",
    "build:cf": "NITRO_PRESET=cloudflare_pages pnpm --filter web build",
    "preview:cf": "cd apps/web && pnpm dlx wrangler@latest pages dev dist --d1 DB"
  }
}

pnpm-workspace.yaml：

packages:
  - "apps/*"
  - "packages/*"

然后建应用：

pnpm dlx nuxi@latest init apps/web

二、装依赖

cd apps/web

# 内容与 SEO
pnpm add @nuxt/content @nuxtjs/i18n @nuxtjs/sitemap @nuxtjs/robots

# 样式与本地数据库
pnpm add @tailwindcss/vite tailwindcss better-sqlite3

pnpm add -D typescript vue-tsc

对应的版本：

{
  "dependencies": {
    "@nuxt/content": "^3.15.2",
    "@nuxtjs/i18n": "^10.6.0",
    "@nuxtjs/robots": "^6.2.0",
    "@nuxtjs/sitemap": "^8.5.0",
    "@tailwindcss/vite": "^4.3.3",
    "better-sqlite3": "^12.5.0",
    "nuxt": "^3.21.11",
    "tailwindcss": "^4.3.3",
    "vue": "^3.5.41",
    "vue-router": "^4.5.0"
  },
  "devDependencies": {
    "typescript": "^5.9.0",
    "vue-tsc": "^2.2.0"
  }
}

better-sqlite3 是 @nuxt/content 的 peer dependency，本地开发要用，别漏。 它只在本地生效，Cloudflare 上走 D1。

三、nuxt.config.ts

这是整套配置的核心，逐块都有对应的坑，后面会展开：

import tailwindcss from '@tailwindcss/vite'

// 构建期求值，不是运行时。生产构建默认用正式域名，
// 否则 canonical 和 sitemap 会全写成 localhost
const siteUrl
  = process.env.NUXT_PUBLIC_SITE_URL
    || (process.env.NODE_ENV === 'production'
      ? 'https://your-domain.com'
      : 'http://localhost:3000')

export default defineNuxtConfig({
  modules: ['@nuxt/content', '@nuxtjs/i18n', '@nuxtjs/sitemap', '@nuxtjs/robots'],
  compatibilityDate: '2025-01-01',
  devServer: { port: 3100 },

  css: ['~/assets/css/main.css'],
  vite: { plugins: [tailwindcss()] },

  // 图片走静态资源，不进 worker
  nitro: {
    cloudflare: { pages: { routes: { exclude: ['/images/*'] } } },
  },

  runtimeConfig: { public: { siteUrl } },

  // sitemap / robots / canonical 共用这份站点配置
  site: {
    url: siteUrl,
    name: '站名',
    // 真正的收录开关，见坑一
    indexable: process.env.NUXT_PUBLIC_INDEXABLE !== 'false',
  },

  content: {
    // 本地 SQLite，Cloudflare 上切 D1
    database: process.env.NUXT_CONTENT_D1_BINDING
      ? { type: 'd1', bindingName: process.env.NUXT_CONTENT_D1_BINDING }
      : undefined,
    build: {
      markdown: {
        toc: { depth: 3, searchDepth: 3 },
        highlight: {
          theme: { default: 'github-light', dark: 'github-dark' },
          langs: ['js', 'ts', 'vue', 'json', 'bash', 'sh', 'html', 'css',
                  'sql', 'yaml', 'python', 'diff', 'md'],
        },
      },
    },
  },

  i18n: {
    baseUrl: siteUrl,
    locales: [
      { code: 'zh', language: 'zh-Hans', name: '中文', dir: 'ltr', file: 'zh.json' },
    ],
    defaultLocale: 'zh',
    strategy: 'prefix_except_default',   // 默认语言不带前缀，见坑五
    detectBrowserLanguage: false,
  },

  sitemap: {
    sources: ['/api/__sitemap__/urls'],  // 动态路由要手动补，见坑四
  },

  robots: {
    disallow: process.env.NUXT_PUBLIC_INDEXABLE === 'false' ? ['/'] : [],
    // 默认 4 小时太长，改完 robots 要等边缘缓存过期才生效
    cacheControl: 'max-age=600, must-revalidate',
  },
})

四、content.config.ts

内容的字段规则全在这里。schema 用 zod，字段写错构建直接报错， 不会等到线上才发现：

import { defineContentConfig, defineCollection, z } from '@nuxt/content'

const stackItem = z.object({
  layer: z.string(),          // 前端 / 后端 / 支付 / 部署
  name: z.string(),
  note: z.string().optional(),
})

const caseSchema = z.object({
  title: z.string(),
  description: z.string(),
  date: z.string(),
  updated: z.string().optional(),
  category: z.string(),
  tags: z.array(z.string()).default([]),
  sourceUrl: z.string().optional(),
  sourceName: z.string().optional(),
  stack: z.array(stackItem).default([]),
  featured: z.boolean().default(false),
  draft: z.boolean().default(false),
})

export default defineContentConfig({
  collections: {
    // source 里的 zh 是内容的语言分区，跟 URL 前缀无关
    casesZh: defineCollection({ type: 'page', source: 'zh/cases/**', schema: caseSchema }),
    pagesZh: defineCollection({ type: 'page', source: 'zh/pages/**' }),
  },
})

加一个内容类型 = 在这里加一个 collection，其余照着已有的抄。

五、环境变量

.env.example：

# 站点地址。sitemap / canonical / hreflang 都用它
NUXT_PUBLIC_SITE_URL=https://your-domain.com

# 默认允许收录。设为 false 才屏蔽搜索引擎（大改版时临时用）
NUXT_PUBLIC_INDEXABLE=true

# Cloudflare D1 binding 名。不设置则本地用 SQLite 文件
NUXT_CONTENT_D1_BINDING=

只有三个。生产环境这三个都可以不配——nuxt.config.ts 里的默认值 已经覆盖了正确行为，这是刻意设计的，避免忘配变量导致线上出错。

六、部署

Cloudflare Pages 连上 GitHub 仓库，填三项设置（见后面「关键配置」）， 建一个 D1 数据库并绑定为 DB，然后推送到 main 即可。

本地想验证 Cloudflare 产物：

pnpm run build:cf
pnpm run preview:cf     # 带本地 D1，行为与线上一致

目录结构

apps/web/
├── content/                     # ← 写作只动这里
│   └── zh/                      #   按语言分目录，语言代码即目录名
│       ├── cases/               #   案例，一个 .md 一篇
│       ├── solutions/           #   技术方案，slug 与案例一一对应
│       ├── templates/           #   开发模板
│       └── pages/               #   关于、披露声明等单页
│
├── public/                      # ← 静态资源，原样拷进产物
│   ├── images/                  #   插图放这儿，正文用 /images/xxx.png 引用
│   └── favicon.ico
│
├── content.config.ts            # ← 内容 schema，字段规则的唯一出处
│
├── pages/                       # 文件路由，路径即 URL
│   ├── index.vue                #   /
│   ├── about.vue                #   /about
│   ├── disclosure.vue           #   /disclosure
│   ├── cases/
│   │   ├── index.vue            #   /cases
│   │   └── [slug]/
│   │       ├── index.vue        #   /cases/xxx
│   │       └── solution.vue     #   /cases/xxx/solution
│   └── templates/
│       ├── index.vue
│       └── [slug].vue
│
├── components/
│   ├── content/                 # ← MDC 组件，可在 Markdown 里直接用
│   │   ├── Callout.vue          #   ::callout
│   │   ├── Figure.vue           #   ::figure  带图注的插图
│   │   ├── Prompt.vue           #   ::prompt
│   │   ├── Stack.vue            #   ::stack
│   │   └── Steps.vue            #   ::steps
│   ├── AppHeader.vue            # 导航栏，加模块要改这里
│   ├── AppFooter.vue
│   ├── CaseCard.vue
│   └── TemplateCard.vue
│
├── composables/                 # 数据访问层，页面不直接查库
│   ├── useCases.ts
│   └── useTemplates.ts
│
├── constants/                   # ← 分类定义，加分类只改这里
│   ├── categories.ts            #   案例分类：按变现模式
│   └── template-kinds.ts        #   模板分类：按产物类型
│
├── i18n/locales/zh.json         # ← 界面文案，所有 t('xxx') 的出处
├── assets/css/main.css          # 全局样式与 .prose 排版
├── layouts/default.vue
├── server/api/__sitemap__/      # 动态路由的 sitemap 来源
├── types/content.ts             # 与 schema 对应的 TS 类型
└── nuxt.config.ts

标 ← 的六个位置是日常真正会碰的，其余基本一次写好不用再动。

常见操作对应改哪里

最后一行那四步缺一不可。少了 sitemap 那步，新模块的页面能访问但搜索引擎不知道它存在。

.claude/skills/case-breakdown/
├── SKILL.md                    # 触发条件与工作流
└── references/
    ├── frontmatter.md          # 字段规范
    ├── scoring.md              # 评分口径
    ├── mdc.md                  # 组件用法
    └── solution-guide.md       # 技术方案的写法

NITRO_PRESET=cloudflare_pages nuxt build

content: {
  database: process.env.NUXT_CONTENT_D1_BINDING
    ? { type: 'd1', bindingName: process.env.NUXT_CONTENT_D1_BINDING }
    : undefined,
}

nitro: {
  cloudflare: { pages: { routes: { exclude: ['/images/*'] } } },
}

site: {
  url: siteUrl,
  indexable: process.env.NUXT_PUBLIC_INDEXABLE !== 'false',
}

const siteUrl = process.env.NUXT_PUBLIC_SITE_URL || 'http://localhost:3000'

const siteUrl
  = process.env.NUXT_PUBLIC_SITE_URL
    || (process.env.NODE_ENV === 'production'
      ? 'https://your-domain.com'
      : 'http://localhost:3000')

const toRoute = (path: string) => path.replace(/^\/zh(?=\/|$)/, '') || '/'

sitemap: { sources: ['/api/__sitemap__/urls'] }

i18n: {
  defaultLocale: 'zh',
  strategy: 'prefix_except_default',   // 默认语言不带前缀
}

routeRules: {
  '/zh': { redirect: { to: '/', statusCode: 301 } },
  '/zh/**': { redirect: { to: '/**', statusCode: 301 } },
}

robots: {
  cacheControl: 'max-age=600, must-revalidate',
}

curl -sI --noproxy '*' https://your-domain.com/ | head -3

# nameserver 换过来了吗（应返回 *.ns.cloudflare.com）
dig +short NS your-domain.com

# 根域名和 www 都能通吗（www 报 522 = 漏加自定义域）
curl -sI --noproxy '*' https://www.your-domain.com/ | head -1

# worker 跑起来了吗（不是 404、不是 Cloudflare 兜底页）
curl -sI --noproxy '*' https://your-domain.com/ | head -3

# 收录开了吗（要看到 indexable）
curl -s --noproxy '*' https://your-domain.com/robots.txt | grep "START nuxt-robots"

# canonical 是正式域名还是 localhost
curl -s --noproxy '*' https://your-domain.com/ | grep -c "localhost"

# sitemap 里有几条，正文页在不在
curl -s --noproxy '*' -L https://your-domain.com/sitemap.xml | grep -c "<loc>"