知识库的持续维护策略

<!-- docs/CHANGELOG.md -->
# 知识库变更日志
 
## 2026-04-12
- 更新第 84 章：补充 Nuxt 4.1 新增的 `useRouteQuery` composable
- 修复第 66 章：Pinia SSR 示例中的 `skipHydrate` 用法已过时
 
## 2026-03-28
- 新增第 79 章：Module Federation 配置更新为 vite-plugin-federation 2.0
- 更新第 67 章：Lighthouse CI 配置更新为 v0.14
 
## 2026-03-15
- 全量检查：Nuxt 4.0.2 发布，无 Breaking Changes

# .github/workflows/version-check.yml
name: Check Dependencies
on:
  schedule:
    - cron: '0 9 * * 1'  # 每周一上午 9 点
 
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
 
      - name: Check outdated packages
        run: |
          pnpm outdated --format json > outdated.json || true
 
      - name: Check Nuxt version
        run: |
          LATEST=$(npm view nuxt version)
          CURRENT=$(node -e "console.log(require('./package.json').dependencies.nuxt)")
          if [ "$LATEST" != "$CURRENT" ]; then
            echo "⚠️ New Nuxt version available: $LATEST (current: $CURRENT)"
          fi
 
      - name: Create issue if updates needed
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs')
            const outdated = JSON.parse(fs.readFileSync('outdated.json', 'utf-8'))
            if (Object.keys(outdated).length > 0) {
              await github.rest.issues.create({
                owner: context.repo.owner,
                repo: context.repo.repo,
                title: `📦 Dependencies update check - ${new Date().toISOString().split('T')[0]}`,
                body: '```json\n' + JSON.stringify(outdated, null, 2) + '\n```',
                labels: ['maintenance']
              })
            }

必须更新知识库的情况：
- [ ] Nuxt 大版本发布（4.x → 5.x）
- [ ] Nuxt 小版本中包含 Breaking Changes
- [ ] 核心模块（@nuxt/ui, @nuxt/image 等）大版本更新
- [ ] Vue 大版本更新
- [ ] Nitro 大版本更新
- [ ] 文章中引用的第三方库 API 变化

每次 Nuxt 版本更新后：
1. [ ] 阅读 Release Notes 和 Migration Guide
2. [ ] 搜索知识库中受影响的 API / 配置项
3. [ ] 更新相关章节的代码示例
4. [ ] 在 CHANGELOG.md 记录变更
5. [ ] 运行 VitePress build 验证无报错
6. [ ] 如有重大变化，在文章开头添加版本提示

<!-- 在受影响的章节开头添加 -->
::: warning 版本更新
本章内容基于 Nuxt 4.0 编写。Nuxt 4.2 中 `useAsyncData` 新增了 `dedupe` 
选项，详见 [Release Notes](https://github.com/nuxt/nuxt/releases/tag/v4.2.0)。
:::

// scripts/check-outdated-content.ts
import { readdir, readFile } from 'fs/promises'
import { join } from 'path'
 
interface CheckResult {
  file: string
  line: number
  issue: string
  severity: 'warning' | 'error'
}
 
const OUTDATED_PATTERNS = [
  { pattern: /nuxt\.config\.js/g, message: 'Nuxt4 使用 nuxt.config.ts（TypeScript）' },
  { pattern: /process\.client/g, message: '推荐使用 import.meta.client' },
  { pattern: /process\.server/g, message: '推荐使用 import.meta.server' },
  { pattern: /useAsyncData\([^)]*\)\s*$/gm, message: '检查是否需要 deep: true' },
  { pattern: /~\/server\//g, message: 'Nuxt4 中 ~ 指向 app/，服务端应使用 ~~/' },
  { pattern: /buildModules/g, message: 'Nuxt4 移除了 buildModules，使用 modules' },
  { pattern: /target:\s*['"]static['"]/g, message: 'Nuxt4 移除了 target，使用 routeRules' },
]
 
async function scanFiles(dir: string): Promise<CheckResult[]> {
  const results: CheckResult[] = []
  const files = await readdir(dir, { recursive: true })
 
  for (const file of files) {
    if (!file.endsWith('.md')) continue
    const content = await readFile(join(dir, file), 'utf-8')
    const lines = content.split('\n')
 
    for (const { pattern, message } of OUTDATED_PATTERNS) {
      lines.forEach((line, i) => {
        // 跳过代码块中标记为 ❌ 的示例（已知的反面教材）
        if (line.includes('❌')) return
        if (pattern.test(line)) {
          results.push({ file, line: i + 1, issue: message, severity: 'warning' })
        }
        pattern.lastIndex = 0
      })
    }
  }
 
  return results
}
 
// 运行
const results = await scanFiles('./docs/nuxt')
console.table(results)

## Prompt: 知识库过时内容审查
 
你是 Nuxt4 专家。请审查以下技术文章，检查：
 
1. **API 是否过时**：是否使用了已废弃或已更名的 API
2. **最佳实践是否当前**：推荐做法是否仍然是社区共识
3. **代码示例是否可运行**：语法是否正确，import 是否完整
4. **版本兼容性**：是否标注了适用的 Nuxt 版本范围
 
当前 Nuxt 版本：4.x
当前 Vue 版本：3.5+
当前 Nitro 版本：3.x
 
输出格式：
- 文件名
- 行号范围
- 问题描述
- 建议修复

# .github/workflows/content-check.yml
name: Content Quality Check
on: [pull_request]
 
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm install
      - name: Check outdated patterns
        run: npx tsx scripts/check-outdated-content.ts
      - name: Build check
        run: pnpm docs:build
      - name: Link check
        run: npx linkinator docs/.vitepress/dist --recurse

## 单篇 Review Checklist
 
### 准确性
- [ ] 所有代码示例在最新 Nuxt 版本上可运行
- [ ] API 用法与官方文档一致
- [ ] 配置项名称和格式正确
- [ ] 版本号和链接正确
 
### 完整性
- [ ] 关键概念有解释，不假设读者已知
- [ ] 常见问题有覆盖
- [ ] 错误处理有示例
 
### 可读性
- [ ] 代码示例简洁，删除了无关代码
- [ ] 表格和列表清晰
- [ ] 注释说明了"为什么"而不只是"做什么"
 
### 时效性
- [ ] 没有使用已废弃的 API
- [ ] 推荐的工具/库仍在活跃维护
- [ ] 性能数据和基准测试在合理范围内

<!-- 每篇文章底部添加反馈组件 -->
<template>
  <div class="mt-16 pt-8 border-t">
    <p class="text-gray-500">这篇文章对你有帮助吗？</p>
    <div class="flex gap-2 mt-2">
      <button @click="feedback('helpful')">👍 有帮助</button>
      <button @click="feedback('outdated')">⏰ 内容过时</button>
      <button @click="feedback('error')">🐛 发现错误</button>
    </div>
  </div>
</template>

<!-- TODOS.md -->
# 知识库技术债
 
## P0 - 立即修复
- [ ] 第 42 章：useFetch 示例缺少错误处理
 
## P1 - 一周内
- [ ] 第 65 章：prerenderRoutes API 在 Nuxt 4.1 中参数有变化
- [ ] 第 80 章：GraphQL Yoga 升级到 v5，API 有变化
 
## P2 - 下个月
- [ ] 第 79 章：补充 Module Federation 2.0 的新特性
- [ ] 第 81 章：MeiliSearch v1.8 新增向量搜索
 
## P3 - 有空就改
- [ ] 全局：统一代码示例中的变量命名风格
- [ ] 全局：补充更多 TypeScript 类型注解

// scripts/maintenance.ts
 
// 1. 检查所有待补充的占位符
async function findPlaceholders(dir: string) {
  const files = await readdir(dir, { recursive: true })
  for (const file of files) {
    if (!file.endsWith('.md')) continue
    const content = await readFile(join(dir, file), 'utf-8')
    if (content.includes('待补充') || content.includes('TODO')) {
      console.warn(`⚠️ ${file}: contains placeholder content`)
    }
  }
}
 
// 2. 检查死链接
async function findDeadLinks(dir: string) {
  const files = await readdir(dir, { recursive: true })
  const linkPattern = /\[([^\]]+)\]\(([^)]+)\)/g
 
  for (const file of files) {
    if (!file.endsWith('.md')) continue
    const content = await readFile(join(dir, file), 'utf-8')
    let match: RegExpExecArray | null
 
    while ((match = linkPattern.exec(content)) !== null) {
      const url = match[2]
      if (url.startsWith('http')) {
        try {
          const res = await fetch(url, { method: 'HEAD' })
          if (!res.ok) console.warn(`🔗 ${file}: dead link ${url} (${res.status})`)
        } catch {
          console.warn(`🔗 ${file}: unreachable ${url}`)
        }
      }
    }
  }
}
 
// 3. 统计文章数据
async function generateStats(dir: string) {
  const files = await readdir(dir, { recursive: true })
  let totalWords = 0
  let totalCodeBlocks = 0
  let articleCount = 0
 
  for (const file of files) {
    if (!file.endsWith('.md')) continue
    articleCount++
    const content = await readFile(join(dir, file), 'utf-8')
    totalWords += content.length
    totalCodeBlocks += (content.match(/```/g) || []).length / 2
  }
 
  console.log(`📊 知识库统计：`)
  console.log(`   文章数：${articleCount}`)
  console.log(`   总字数：${(totalWords / 10000).toFixed(1)} 万字`)
  console.log(`   代码块：${totalCodeBlocks} 个`)
}

1. **准确性优先**：宁可删除过时内容，也不留着误导读者
2. **增量更新**：每次 Nuxt 发版后增量更新受影响章节，不做全量重写
3. **版本标注**：重大变化在文章开头标注版本提示
4. **自动化优先**：能用脚本检测的问题不靠人工检查
5. **社区驱动**：鼓励读者反馈错误和过时内容