Vue.js项目在VS Code中调试全攻略：解决断点映射与配置问题

对于前端开发者，尤其是在使用现代框架如 Vue.js 进行开发时，高效的调试能力是提升开发体验和问题排查效率的关键。本文将手把手教你如何在 Visual Studio Code 中配置并启动对 Vue.js 项目的调试，涵盖从项目创建、生成 Sourcemap 到配置文件编写的完整流程，并分享在实际调试中可能遇到的“坑”及应对思路。

文中会以一个全新的 Vue.js 项目作为模板进行配置，你可以跟随教程一步步操作，也可以将配置方案应用到已有的项目中。

文中涉及的完整示例项目仓库地址：https://github.com/mrlmx/debug-vuejs-project-with-vscode

创建项目

首先，我们直接使用 Vue 官方提供的 create-vue 脚手架，创建一个全新的 Vue 3 项目。

npm init vue@latest

请注意：通过上述命令创建的将是一个基于 Vite 的项目，而不是基于 Webpack 的。

项目创建完成后，在 VS Code 中打开它：

code ./debug-vuejs-project-with-vscode

• code 是 VS Code 自带的命令，如果你的系统提示没有此命令，可以参考官方文档 launching-from-the-command-line 进行设置。
• debug-vuejs-project-with-vscode 是我使用的项目名称，你需要替换为你自己的。

生成 Sourcemap 文件

调试的核心在于将运行时的代码映射回源代码，这依赖于 Sourcemap 文件。你需要根据项目的构建工具进行相应配置。

Vite

如果你是通过 create-vue 创建的项目，则需要修改 vite.config.ts 配置文件，确保在开发环境生成 sourcemap 文件。

export default defineConfig({
  build: {
    sourcemap: true,
  },
  // other configs...
});

更多关于 Vite Sourcemap 的配置，请参考其官方文档。

Vue CLI

对于通过 vue-cli 创建的项目，则需要修改 vue.config.js 配置文件。

module.exports = {
  configureWebpack: {
    devtool: "source-map"
  }
  // other configs...
};

Webpack

如果是自己搭建的 Webpack 项目，则在对应的 Webpack 配置文件中设置即可。

module.exports = {
  devtool: "source-map",
  // other configs...
};

配置文件

要让 VS Code 的调试器认识你的项目并正确工作，需要在项目根目录下的 .vscode 文件夹中创建两个配置文件：launch.json 和 tasks.json。

创建 launch.json

launch.json 是 VS Code 调试的核心配置文件。你可以通过以下步骤创建（如果项目中已存在该文件，则可跳过）：

1. 点击 VS Code 左侧活动栏的“运行和调试”图标（或按 Ctrl+Shift+D）。
2. 点击“创建一个 launch.json 文件”。
3. 在弹出的选择器中，选择 Web App (Edge)。当然，根据你的偏好，选择 Web App (Chrome) 也是完全可以的。

系统生成的 launch.json 文件内容比较简单，我们需要用更详细的配置来替换它。将文件内容替换为以下配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      // 使用 Edge 浏览器调试
      "type": "msedge",
      // 使用 Chrome 浏览器调试
      // "type": "chrome",

      "request": "launch",
      "name": "vuejs: msedge",

      // 项目的访问地址（需要改成你项目开发环境对应的地址和端口号）
      "url": "http://localhost:5173",

      "webRoot": "${workspaceFolder}",
      "pathMapping": {
        "/_karma_webpack_": "${workspaceFolder}"
      },
      "sourceMapPathOverrides": {
        "webpack:/*": "${webRoot}/*",
        "/./*": "${webRoot}/*",
        "/src/*": "${webRoot}/*",
        "/*": "*",
        "/./~/*": "${webRoot}/node_modules/*"
      },

      // 设置进入 debug 环境之前需要执行的任务。
      // 此名称对应项目中 .vscode 目录下 tasks.json 文件中的 label 属性）
      "preLaunchTask": "vuejs: start"
    }
  ]
}

配置文件中有几个关键点需要注意：

• type：指定调试器类型。msedge 对应 Microsoft Edge 浏览器，chrome 对应 Google Chrome 浏览器。
• url：调试启动时浏览器自动访问的地址。务必将其修改为你本地开发服务器的地址（例如 Vite 默认是 http://localhost:5173）。
• preLaunchTask：这是一个非常实用的功能，它指定在启动调试之前自动运行的任务。这里它指向一个名为 vuejs: start 的任务，该任务定义在接下来要创建的 tasks.json 文件中，用于自动启动开发服务器。

创建 tasks.json

接下来，在 .vscode 目录下创建 tasks.json 文件，用于定义 preLaunchTask 中引用的任务。将以下内容粘贴进去：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "vuejs: start",
      "type": "npm",
      // 需要执行的命令（对应于 package.json 中的 scripts 命令）
      "script": "dev",
      "isBackground": true
    }
  ]
}

这个配置的作用是执行 npm run dev 命令来启动开发服务器。如果你的项目启动命令是 yarn dev 或其他，只需将 "script" 的值修改为对应的脚本名即可。

注意：type 字段的可选值是 shell 或 process，而不是 yarn 或 npm。这里的 “npm” 是 VS Code 识别的一种特定任务类型，它会自动调用 npm 来执行脚本。

设置断点

配置文件就绪后，我们就可以在代码中设置断点了。修改项目中的 src/views/AboutView.vue 文件，并添加一些简单的逻辑用于调试。

<script lang="ts" setup>
import { reactive, ref } from "vue";

const other = reactive([
  { name: "lmx", age: 18 },
  { name: "foo", age: 20 },
  { name: "bar", age: 12 },
]);
const count = ref(0);

const handlePlus = () => {
  console.log("plus before", count.value);
  count.value++;
  console.log("plus after", count.value);
};

const handleMinus = () => {
  console.log("minus before", count.value);
  count.value--;
  console.log("minus after", count.value);
};
</script>

<template>
  <div class="about">
    <h1>This is an about page</h1>
    <div>
      <p>{{ count }}</p>
      <button @click="handlePlus">plus</button>
      <button @click="handleMinus">minus</button>
      <hr style="margin: 20px 0" />
      <p v-for="item of other" :key="item.name">
        {{ item.name }}: {{ item.age }}
      </p>
    </div>
  </div>
</template>

然后，在第 13 行（handlePlus 函数内）和第 19 行（handleMinus 函数内）左侧的空白处点击鼠标左键，分别添加两个断点。

一个重要的注意事项

务必在启动 Debug 会话之前打好断点。

这是因为 Vue 的单文件组件（*.vue）在运行时会被编译成纯 JavaScript 文件。调试器实际上是在操作编译后的文件，并通过 Sourcemap 将其映射回你的源代码。如果在调试启动后才在源文件中添加新断点，运行中的编译文件无法感知到这个变化，导致新断点失效。

只有当你修改源代码并触发重新编译后，新的编译文件才会包含映射到新断点的信息。

关于启动时的任务跟踪弹窗

在启动调试时，你可能会遇到一个弹窗提示：“The task ‘vuejs: start’ cannot be tracked. Make sure to have a problem matcher defined.”。

对于这个提示，目前没有完美的解决方案，但有两个变通方法：

1. 忽略它：直接点击 Debug Anyway 按钮，或者勾选 Remember my choice for this task 后点击按钮，以后就不会再弹出此提示。
2. 手动启动：从 launch.json 配置中移除 “preLaunchTask” 属性。然后在启动调试前，自己手动在终端运行 npm run dev 来启动开发服务器。

启动调试

一切配置妥当，现在可以启动调试了。有两种启动方式：

快捷键启动 (F5)

如果你的 launch.json 中只有一个调试配置，那么最方便的方式就是直接按下 F5 键。VS Code 会自动启动任务并打开浏览器，进入调试模式。

手动选择启动

如果你的项目配置了多个调试选项（例如同时支持 Edge 和 Chrome），则需要手动选择。

在调试视图顶部的下拉菜单中，你会看到所有可用的配置（如 vuejs: msedge 和 vuejs: chrome），选择其中一个再点击运行按钮即可。

一个多配置的 launch.json 示例片段如下：

{
  “version”: “0.2.0”,
  “configurations”: [
    {
      “type”: “msedge”,
      “request”: “launch”,
      “name”: “vuejs: msedge”,
      “url”: “http://localhost:5173”,
      “webRoot”: “${workspaceFolder}”,
      // ... 其他配置
    },
    {
      “type”: “chrome”,
      “request”: “launch”,
      “name”: “vuejs: chrome”,
      “url”: “http://localhost:5173”,
      “webRoot”: “${workspaceFolder}”,
      // ... 其他配置
    }
  ]
}

调试过程中遇到的问题与对策

在实际的 Debugging 过程中，可能会遇到一些令人困惑的情况。下面结合示意图，分享我遇到的几个典型问题及解决思路。

上图清晰地展示了调试时的状态：

• 标注 1：是我们的源代码文件 AboutView.vue。
• 标注 2：是运行时命中断点后，VS Code 自动打开的编译后的 JavaScript 文件。其文件名可能带有时间戳参数，如 AboutView.vue?t=1661699383436，以避免缓存。
• 标注 3 & 4：分别对应源代码第13行和第19行的断点。

问题一：如何中途添加新断点？

如前所述，启动后直接在源文件加断点无效。有两个方法：

1. 在编译后的文件中添加：直接在 VS Code 自动打开的编译文件（如图中标注2的文件）里点击添加断点。缺点是“一次性”的，因为一旦源文件修改导致重新编译，这个针对旧编译文件的断点就失效了。
2. 在源文件添加并触发重编译：在源文件中打好新断点，然后对源代码做一处微小修改（例如增删一个空格或注释），触发项目重新编译。新的编译文件就会包含对新断点的映射。

问题二：断点行号映射错位

有时你会发现，源文件和编译文件的行号虽然对上，但断点实际暂停的位置却不是你想要的那行代码。

这是因为 Vue 的编译器（@vue/compiler-sfc）会将 <script setup> 语法糖转换成标准的 Composition API 代码，并插入一些运行时辅助代码，导致行号映射出现偏差。

解决方案：对于至关重要的调试点，可以直接在源代码中使用 debugger; 语句。这样可以确保执行流一定会在此处暂停。暂停后，你可以在对应的编译文件中再添加其他观察断点。

const handlePlus = () => {
  debugger; // 强制在此处中断
  console.log("plus before", count.value);
  count.value++;
  console.log("plus after", count.value);
};

问题三：每次修改都会产生新编译文件，旧断点残留

每次保存源文件，Vite 都会生成一个新的编译文件。这导致之前你在旧编译文件上设置的所有断点都变成了“无效”状态（虽然它们仍显示在断点面板中），影响观感。

临时处理方案：调试结束后，可以点击 VS Code 断点面板上的 Remove All Breakpoints 按钮，一次性清理所有断点。

以上就是我在配置和使用 VS Code 调试 Vue.js 项目时总结的全套流程和遇到的典型问题。希望这份指南能帮助你建立顺畅的调试工作流。如果你有更好的解决方案或技巧，欢迎在云栈社区的相关板块进行分享和讨论。