Claude Code 调试工作流完全指南：从报错到根因的 AI 排错之道

// 一个典型的 Node.js 错误堆栈
TypeError: Cannot read properties of undefined (reading 'title')
    at PostCard (/app/components/PostCard.tsx:12:28)        // ← 你的代码，重点看这里
    at renderWithHooks (/node_modules/react-dom/...)         // ← 框架代码，通常跳过
    at mountIndeterminateComponent (/node_modules/react-dom/...)
    at beginWork (/node_modules/react-dom/...)
    at HTMLUnknownElement.callCallback (/node_modules/react-dom/...)

# 基础用法：直接粘贴错误
> 这个报错是什么意思，怎么修？
> TypeError: Cannot read properties of undefined (reading 'title')
>     at PostCard (/app/components/PostCard.tsx:12:28)
 
# 进阶用法：带上下文
> 运行 npm run build 时报了这个错：
> [粘贴完整错误]
> 相关文件是 PostCard.tsx 和 lib/posts.ts
> 这个错误只在 build 时出现，dev 模式正常
 
# 批量错误分析
> 控制台有以下 3 个警告和 1 个错误，帮我按优先级排序并逐个分析：
> [粘贴所有错误信息]

// 假设一个复杂函数返回了错误结果
function processData(input: RawData): ProcessedData {
  const step1 = parseInput(input)
  console.log('step1:', step1)  // ← 检查点 1
 
  const step2 = validateData(step1)
  console.log('step2:', step2)  // ← 检查点 2
 
  const step3 = transformData(step2)
  console.log('step3:', step3)  // ← 检查点 3
 
  const step4 = enrichData(step3)
  console.log('step4:', step4)  // ← 检查点 4
 
  return formatOutput(step4)
}
 
// 先在中间加 log（step2），确定问题在前半段还是后半段
// 然后继续二分，2-3 轮就能定位到具体步骤

# 启动 bisect
git bisect start
git bisect bad                    # 当前版本有 bug
git bisect good abc1234           # 这个 commit 是好的
 
# 自动化 bisect（推荐）
git bisect run npm test           # 用测试结果自动判断 good/bad
 
# bisect 结束后，让 Claude Code 分析
> git bisect 定位到这个 commit 引入了 bug：
> [粘贴 commit hash 和 diff]
> 分析一下这个改动为什么会导致 [描述 bug 现象]

> 帮我写一个 git bisect 脚本，判断条件是：
> 运行 node scripts/check.js 后，输出中不包含 "ERROR"
> 如果包含 ERROR 就是 bad，不包含就是 good

#!/bin/bash
# bisect-check.sh
output=$(node scripts/check.js 2>&1)
if echo "$output" | grep -q "ERROR"; then
  exit 1  # bad
else
  exit 0  # good
fi

# 让 Claude Code 分析日志
> 这是最近 1 小时的应用日志，帮我找出异常模式：
> [粘贴日志]
 
# 更精确的 prompt
> 分析这段日志，关注以下几点：
> 1. 有没有重复出现的错误
> 2. 错误之间有没有时间规律
> 3. 有没有某个请求路径的错误率特别高
> 4. 内存/CPU 使用有没有异常趋势

# 让 Claude Code 追踪数据流
> PostCard 组件报了 undefined 错误。
> 帮我追踪 post.title 这个数据从哪里来的：
> 从 API 响应 → 数据处理 → 状态管理 → 组件 props
> 找出哪一步可能丢失了 title 字段
 
# 追踪函数调用链
> getPostBySlug 函数返回了 null，但不应该。
> 帮我找出所有调用 getPostBySlug 的地方，
> 以及 getPostBySlug 内部调用的所有函数，画出调用关系。

// ❌ 不好的 log
console.log(data)
console.log('here')
console.log(result)
 
// ✅ 结构化 log
console.log('[PostCard] props:', { slug: post.slug, title: post.title })
console.log('[API] /posts response:', { status: res.status, count: data.length })
console.log('[Auth] token check:', { hasToken: !!token, expired: isExpired(token) })

# 自动加结构化 log
> 在 lib/posts.ts 的每个函数入口和出口加上结构化 log，
> 格式：console.log('[Posts] functionName:', { 关键参数 })
> 出口 log 包含返回值的摘要（不要打印完整对象，只打印 count 或 id）
 
# 条件 log（不影响生产环境）
> 帮我在 processOrder 函数里加调试 log，但要满足：
> 1. 只在 NODE_ENV=development 时输出
> 2. 用 console.debug 而不是 console.log
> 3. 调试完后容易一键删除（加 // DEBUG 注释标记）

# 清理所有调试 log
grep -n "// DEBUG" lib/orders.ts

# 让 Claude Code 帮你配置调试环境
> 生成一个 .vscode/launch.json，包含以下调试配置：
> - Next.js 开发服务器调试
> - Vitest 单测调试（能调试单个测试文件）
> - Node.js 脚本调试
> 要求支持 TypeScript source map

> 帮我写一个 debugFetch wrapper，在开发环境下自动记录：
> - 请求方法和 URL
> - 响应状态码和耗时
> - 错误响应的 body（截取前 500 字符）

# 让 Claude Code 帮你追踪状态变化
> 我的 React 组件 UserProfile 渲染了错误的数据。
> 帮我写一个 useStateWithLog hook，在 setState 时打印旧值和新值，
> 方便追踪状态变化的来源。

// ❌ 经典竞态：快速切换页面时，旧请求的响应覆盖新请求
function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState<User | null>(null)
 
  useEffect(() => {
    fetch(`/api/users/${userId}`)
      .then(res => res.json())
      .then(data => setUser(data))  // 如果用户快速切换，旧请求可能后到
  }, [userId])
 
  return <div>{user?.name}</div>
}
 
// ✅ 修复：用 AbortController 取消过期请求
function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState<User | null>(null)
 
  useEffect(() => {
    const controller = new AbortController()
 
    fetch(`/api/users/${userId}`, { signal: controller.signal })
      .then(res => res.json())
      .then(data => setUser(data))
      .catch(err => {
        if (err.name !== 'AbortError') throw err
      })
 
    return () => controller.abort()  // 清理：取消上一次请求
  }, [userId])
 
  return <div>{user?.name}</div>
}

> 检查 components/UserProfile.tsx 中的 useEffect，
> 有没有竞态条件的风险？如果有，帮我修复。
> 要求用 AbortController 模式。

// ❌ 难以调试的 Promise 链
async function syncData() {
  const users = await fetchUsers()
  const enriched = await enrichUsers(users)
  const validated = await validateUsers(enriched)
  await saveUsers(validated)
}
 
// ✅ 加上错误上下文的 Promise 链
async function syncData() {
  let step = ''
  try {
    step = 'fetchUsers'
    const users = await fetchUsers()
 
    step = 'enrichUsers'
    const enriched = await enrichUsers(users)
 
    step = 'validateUsers'
    const validated = await validateUsers(enriched)
 
    step = 'saveUsers'
    await saveUsers(validated)
  } catch (error) {
    throw new Error(`syncData failed at ${step}: ${error.message}`, {
      cause: error,
    })
  }
}

# 让 Claude Code 分析事件循环问题
> 这段代码的执行顺序是什么？为什么 console.log 的输出顺序和我预期的不一样？
> [粘贴代码]

// 经典面试题，也是真实 bug 的来源
console.log('1')
setTimeout(() => console.log('2'), 0)
Promise.resolve().then(() => console.log('3'))
console.log('4')
// 输出：1, 4, 3, 2（不是 1, 2, 3, 4）

# 让 Claude Code 帮你生成环境诊断脚本
> 帮我写一个 scripts/doctor.sh，检查 Node 版本、npm 版本、
> .env.local 是否存在、node_modules 是否完整、端口是否被占用

// ❌ 直接使用，未验证
const apiUrl = process.env.API_URL  // 可能是 undefined
 
// ✅ 启动时验证
function getRequiredEnv(key: string): string {
  const value = process.env[key]
  if (!value) throw new Error(`Missing env: ${key}`)
  return value
}

> 扫描项目中所有 process.env 的使用，列出哪些有默认值、哪些没有

// ❌ 硬编码路径分隔符
const filePath = 'content/' + locale + '/' + slug + '.mdx'
 
// ✅ 使用 path.join（跨平台安全）
import path from 'path'
const filePath = path.join('content', locale, `${slug}.mdx`)

> npm ls react 显示有多个版本，帮我分析哪些包引入了不同版本，
> 怎么用 overrides 统一

# 让 Claude Code 分析 Lighthouse 报告
> 我的 Lighthouse 性能分数只有 62，这是报告摘要：
> - FCP: 3.2s
> - LCP: 5.1s
> - TBT: 890ms
> - CLS: 0.15
> 帮我按优先级列出优化方案，先解决影响最大的。
 
# Core Web Vitals 逐项优化
> LCP 是 5.1s，目标是降到 2.5s 以下。
> 当前页面的 LCP 元素是一张 hero image。
> 帮我分析可能的优化方向并生成代码。

// ❌ 原始写法
<img src="/hero.jpg" alt="Hero" />
 
// ✅ 使用 next/image + priority（LCP 元素禁用懒加载）
import Image from 'next/image'
<Image src="/hero.jpg" alt="Hero" width={1200} height={630} priority sizes="100vw" />

> 帮我配置 @next/bundle-analyzer，分析 build 产物中哪些包最大、有没有重复打包

// ❌ 内存泄漏：定时器未清理
useEffect(() => {
  setInterval(() => fetchNotifications(), 5000)
}, [])
 
// ✅ 修复：返回清理函数
useEffect(() => {
  const timer = setInterval(() => fetchNotifications(), 5000)
  return () => clearInterval(timer)
}, [])

> 检查项目中所有 useEffect，找出没有返回清理函数但创建了定时器或监听器的地方

> 这个 API 接口响应时间 > 2s，帮我分析数据库查询日志：
> 哪个查询最慢、是否缺少索引、有没有 N+1 问题

// 结构化日志格式（方便后续搜索和分析）
const logger = {
  info: (message: string, context: Record<string, unknown>) =>
    console.log(JSON.stringify({ level: 'info', message, timestamp: new Date().toISOString(), ...context })),
  error: (message: string, error: Error, context: Record<string, unknown>) =>
    console.error(JSON.stringify({
      level: 'error', message, timestamp: new Date().toISOString(),
      error: { name: error.name, message: error.message, stack: error.stack },
      ...context,
    })),
}

# 让 Claude Code 分析生产日志
> 这是过去 1 小时的错误日志（JSON 格式），帮我分析：
> 1. 按错误类型分组，统计各类型出现次数
> 2. 找出错误率最高的 API 路径
> 3. 有没有错误集中爆发的时间段
> 4. 给出排查优先级建议

> 帮我在 Next.js 项目中集成 Sentry：
> 1. 安装 @sentry/nextjs
> 2. 配置 client 和 server 的 sentry config
> 3. 配置 source map 上传
> 4. 过滤掉 AbortError 等无需上报的错误
> 5. 确保不会泄露 PII

# 让 Claude Code 帮你构造复现环境
> 生产环境报了这个错误：[粘贴 Sentry 错误详情]
> 帮我分析复现条件（数据、用户状态、时序），
> 然后写一个测试用例来复现这个 bug。

> 帮我实现一个简单的特性开关系统：
> - 支持按用户 ID 哈希做百分比灰度
> - 支持从环境变量读取开关状态
> - 在组件中用 useFeatureFlag('newCheckout') 调用

// 自定义错误类，包含 code 字段用于分类
class AppError extends Error {
  constructor(
    message: string,
    public code: string,
    public statusCode: number = 500,
  ) {
    super(message)
    this.name = 'AppError'
  }
}
 
// API 路由统一错误格式：{ error: { code, message } }

# Debugging
 
## Error Handling Conventions
- Custom errors: use AppError class from lib/errors.ts
- API errors: return { error: { code, message, details? } }
- All async functions must have try-catch
- Never swallow errors silently
- Include context in error messages: function name, key params, operation
 
## Logging Conventions
- Format: [Module] action { key: value }
- Levels: error > warn > info > debug
- Production: info and above only
- Never log: passwords, tokens, PII
- Always log: requestId, duration for slow operations (>500ms)
 
## Debug Workflow
- First: read the error message carefully
- Second: check recent git changes (git log --oneline -10)
- Third: add structured logs at key checkpoints
- Fourth: write a failing test that reproduces the bug
- Fifth: fix and verify the test passes
- Sixth: check for similar patterns elsewhere in the codebase
 
## Known Issues
- Hydration mismatch: check for Date/time rendering without useEffect
- CORS errors in dev: use next.config.ts rewrites, not proxy
- Hot reload breaks WebSocket: restart dev server

> Next.js 控制台报了 Hydration Mismatch 错误：
> Server: "2026年3月22日" Client: "3/22/2026"
> 这是什么意思？可能的原因有哪些？

> 帮我在项目中搜索所有日期格式化的代码，
> 特别是 toLocaleDateString、Intl.DateTimeFormat、new Date() 在 JSX 中的使用

// components/PostDate.tsx（问题代码）
export function PostDate({ date }: { date: string }) {
  const formatted = new Date(date).toLocaleDateString('zh-CN', {
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  })
 
  return <time dateTime={date}>{formatted}</time>
}

> 找到了问题代码在 components/PostDate.tsx。
> 分析一下为什么 toLocaleDateString('zh-CN') 在服务端和客户端的结果不同？

> 明白了根因。帮我修复这个问题，要求：
> 1. 服务端和客户端的输出必须一致
> 2. 保持中文日期格式
> 3. 不依赖运行环境的 locale 数据

// components/PostDate.tsx（修复后）
export function formatDate(dateString: string, locale: string): string {
  const date = new Date(dateString)
  const year = date.getFullYear()
  const month = date.getMonth() + 1
  const day = date.getDate()
 
  if (locale === 'zh') {
    return `${year}年${month}月${day}日`
  }
  const months = [
    'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
    'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
  ]
  return `${months[date.getMonth()]} ${day}, ${year}`
}
 
export function PostDate({ date, locale }: { date: string; locale: string }) {
  return <time dateTime={date}>{formatDate(date, locale)}</time>
}

> 用方案 A 修复。修复后帮我验证：
> 1. 运行 npm run build，确认没有 hydration 警告
> 2. 检查中文和英文两种 locale 的日期显示是否正确

# 构建验证
npm run build
# ✓ 无 hydration 警告
 
# 手动验证
# 访问 /zh/blog/test-post → 显示 "2026年3月22日" ✓
# 访问 /en/blog/test-post → 显示 "Mar 22, 2026" ✓

> 修复验证通过了。帮我写回归测试，覆盖中英文格式和边界情况。

// __tests__/format-date.test.ts
import { describe, it, expect } from 'vitest'
import { formatDate } from '@/components/PostDate'
 
describe('formatDate', () => {
  it('中文格式：YYYY年M月D日', () => {
    expect(formatDate('2026-03-22', 'zh')).toBe('2026年3月22日')
    expect(formatDate('2026-01-01', 'zh')).toBe('2026年1月1日')
    expect(formatDate('2024-02-29', 'zh')).toBe('2024年2月29日')  // 闰年
  })
 
  it('英文格式：Mon DD, YYYY', () => {
    expect(formatDate('2026-03-22', 'en')).toBe('Mar 22, 2026')
    expect(formatDate('2026-12-25', 'en')).toBe('Dec 25, 2026')
  })
})

# 在 CLAUDE.md 的 Known Issues 中添加：
 
## Known Issues
- Hydration mismatch with dates: Never use toLocaleDateString() in SSR components.
  Use the manual formatDate() function from components/PostDate.tsx instead.
  Reason: Node.js and browsers have different ICU locale data.