断点调试: 使用 VS Code / Cursor 调试器

Cursor 基于 VS Code，调试配置兼容。检查项目结构并创建调试配置： 创建适合 Cursor 的调试配置。Cursor 与 VS Code 调试配置兼容，可直接使用。

已创建的配置

1. .vscode/launch.json - 调试配置文件
2. .vscode/settings.json - 调试相关设置

调试配置说明

• 🚀 Debug Backend (Launch) - 从头启动并调试（推荐）
• 🔗 Attach to Backend (Port 9229) - 附加到已运行的进程
• 🐛 Debug Stats Service Only - 只调试统计服务
• 📊 Debug Init DB Script - 调试数据库初始化脚本

调试技巧

在代码文件中设置断点后：

• 1. 查看变量：在左侧变量面板查看 categories
• 2. 监视表达式：添加 categories.length 到监视面板
• 3. 调试控制台：输入 categories[0]?.name 查看值
• 4. 步进调试：
  • F10 - 单步跳过
  • F11 - 单步进入
  • F5 - 继续执行

示例：调试 getSourcePie()

async getSourcePie() {
  const Category = (await import('../../models/Category.js')).default;
  
  // 👈 在这里设置断点（第118行）
  const categories = await Category.findAll({
    // ...
  });
  
  // 👈 也可以在这里设置断点（第137行）
  return categories.map(category => {
    // ...
  });
}

启动调试后，访问 /api/stats/overview 接口，程序会在断点处暂停，可以查看所有变量值。

与 VS Code 的区别

Cursor 与 VS Code 的调试功能相同：

• 相同的调试配置格式
• 相同的断点功能
• 相同的变量查看方式
• 相同的调试控制台

可以直接使用，无需额外配置。

launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "🚀 Debug Backend (Launch)",
      "runtimeExecutable": "pnpm",
      "runtimeArgs": ["run", "dev:debug"],
      "skipFiles": ["<node_internals>/**"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen",
      "env": {
        "NODE_ENV": "development",
        "DEBUG": "app:*"
      },
      "cwd": "${workspaceFolder}/packages/backend",
      "restart": true,
      "sourceMaps": true,
      "outputCapture": "std"
    },
    {
      "type": "node",
      "request": "attach",
      "name": "🔗 Attach to Backend (Port 9229)",
      "port": 9229,
      "restart": true,
      "skipFiles": ["<node_internals>/**"],
      "localRoot": "${workspaceFolder}/packages/backend",
      "remoteRoot": "${workspaceFolder}/packages/backend",
      "sourceMaps": true
    },
    {
      "type": "node",
      "request": "launch",
      "name": "🐛 Debug Stats Service Only",
      "program": "${workspaceFolder}/packages/backend/app.js",
      "runtimeExecutable": "node",
      "runtimeArgs": ["--inspect", "--watch"],
      "skipFiles": ["<node_internals>/**"],
      "console": "integratedTerminal",
      "env": {
        "NODE_ENV": "development",
        "DEBUG": "app:stats:*"
      },
      "cwd": "${workspaceFolder}/packages/backend",
      "restart": true
    },
    {
      "type": "node",
      "request": "launch",
      "name": "📊 Debug Init DB Script",
      "program": "${workspaceFolder}/packages/backend/scripts/init-db.js",
      "skipFiles": ["<node_internals>/**"],
      "console": "integratedTerminal",
      "env": {
        "NODE_ENV": "development"
      },
      "cwd": "${workspaceFolder}/packages/backend"
    }
  ],
  "compounds": [
    {
      "name": "🎯 Debug Full Stack",
      "configurations": ["🚀 Debug Backend (Launch)"],
      "presentation": {
        "hidden": false,
        "group": "",
        "order": 1
      },
      "stopAll": true
    }
  ]
}

setting.json

{
  "debug.node.autoAttach": "on",
  "debug.javascript.autoAttachFilter": "smart",
  "debug.javascript.breakOnConditionalError": true,
  "debug.javascript.unmapMissingSources": true,
  "files.exclude": {
    "**/node_modules": true,
    "**/.git": true
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/logs": true
  }
}

---

Cursor/VS Code 调试配置说明

🎯 快速开始

方法1：使用调试面板（推荐）

1. 打开调试面板

   • 按 Cmd+Shift+D (Mac) 或 Ctrl+Shift+D (Windows/Linux)
   • 或点击左侧活动栏的调试图标

2. 选择调试配置

   • 在顶部下拉菜单中选择 🚀 Debug Backend (Launch)

3. 设置断点

   • 在代码行号左侧点击，出现红色圆点
   • 例如：在 packages/backend/modules/stats/service.js 的 getSourcePie() 方法中设置断点

4. 启动调试

   • 按 F5 或点击绿色播放按钮
   • 程序会在断点处暂停

📋 可用的调试配置

🚀 Debug Backend (Launch)

• 用途：从头启动后端并调试
• 特点：自动重启，支持文件监听
• 环境变量 ：DEBUG=app:*

🔗 Attach to Backend (Port 9229)

• 用途：附加到已运行的后端进程
• 前提 ：需要先运行 pnpm run dev:debug
• 适用场景：不想重启服务器时调试

🐛 Debug Stats Service Only

• 用途：专门调试统计服务
• 环境变量 ：DEBUG=app:stats:*
• 适用场景：只关注 stats 模块的调试

📊 Debug Init DB Script

• 用途：调试数据库初始化脚本
• 适用场景：排查数据库初始化问题

🛠️ 调试技巧

1. 设置断点

• 普通断点：点击行号左侧

• 条件断点 ：右键点击行号 → "Add Conditional Breakpoint"

  // 例如：只在 categories.length > 0 时暂停
  categories.length > 0

• 日志断点 ：右键点击行号 → "Add Logpoint"

  // 例如：输出日志但不暂停
  categories.length: {categories.length}

2. 查看变量

• 变量面板：左侧显示当前作用域的所有变量

• 监视面板 ：添加表达式持续监视

  // 例如：
  categories.map(c => c.name)
  categories.reduce((sum, c) => sum + c.get('articleCount'), 0)

• 悬停查看：鼠标悬停在变量上查看值

• 调试控制台：在底部控制台输入表达式查看值

3. 调试控制台命令

在调试控制台（Debug Console）中可以执行：

// 查看变量
categories
categories.length

// 执行表达式
categories.map(c => c.name)

// 调用函数（如果可访问）
this.getSourcePie()

4. 步进调试

• F10 (Step Over)：执行当前行，不进入函数
• F11 (Step Into)：进入函数内部
• Shift+F11 (Step Out)：跳出当前函数
• F5 (Continue)：继续执行到下一个断点

🔍 调试示例：调试 getSourcePie()

1. 在 service.js 中设置断点：

   async getSourcePie() {
     const Category = (await import('../../models/Category.js')).default;
     
     // 👈 在这里设置断点（第118行）
     const categories = await Category.findAll({
       // ...
     });
     
     // 👈 也可以在这里设置断点（第137行）
     return categories.map(category => {
       // ...
     });
   }

2. 启动调试 ：选择 🚀 Debug Backend (Launch) 并按 F5

3. 触发断点 ：访问 /api/stats/overview 接口

4. 查看数据：

   • 在变量面板查看 categories
   • 在监视面板添加：categories.length
   • 在调试控制台输入：categories[0]?.name

⚙️ 环境变量配置

调试配置会自动设置以下环境变量：

• NODE_ENV=development
• DEBUG=app:* (可根据配置调整)

如果需要自定义，可以修改 .vscode/launch.json 中的 env 字段。

🐛 常见问题

1. 断点不生效？

• 确保使用的是 dev:debug 脚本（带 --inspect 标志）
• 检查是否在正确的文件中设置断点
• 尝试重新启动调试会话

2. 无法附加到进程？

• 确保后端正在运行：pnpm run dev:debug
• 检查端口 9229 是否被占用
• 查看终端是否有 "Debugger listening on..." 消息

3. 变量显示为 undefined？

• 可能是异步问题，尝试在下一行设置断点
• 检查变量作用域是否正确
• 使用调试控制台直接执行表达式