本篇目标 ：搭建一个可断点调试、可修改、可打印日志的 Vue3 源码环境。
适用场景 ：阅读
@vue/reactivity、runtime-core、compiler-core等核心模块源码。前置要求：Node.js >= 18，pnpm，VSCode。
一、为什么不能直接 npm install vue读源码？
很多同学一开始会这样做：
npm install vue
node_modules/vue/dist/vue.global.js问题在哪里？
-
这是打包后的产物：变量名被压缩、逻辑被合并，几乎不可读。
-
没有 SourceMap ：你无法在浏览器或 VSCode 中映射到原始
.ts文件。 -
无法修改验证 ：你改了源码，看不到效果，也没法加
console.log。
✅ 正确的姿势 ：直接克隆 Vue3 官方 Monorepo，以开发模式运行。
二、Step 1：Clone 官方仓库
Vue3 使用的是 Monorepo 架构，所有核心模块都在一个仓库中。
git clone https://github.com/vuejs/core.git vue3-core
cd vue3-core目录结构（重点关注这几个）：
packages/
├── reactivity # 响应式系统：ref、reactive、effect
├── runtime-core # 运行时核心：组件、渲染、diff
├── runtime-dom # 浏览器相关：DOM API、事件
├── compiler-core# 编译器核心
├── compiler-dom # 浏览器编译器
└── shared # 公共工具方法三、Step 2：安装依赖（pnpm 是关键）
⚠️ Vue3 官方强制使用 pnpm，不要用 npm 或 yarn。
安装 pnpm
npm install -g pnpm安装依赖
pnpm install⚠️ pnpm 常见坑位（非常重要）
坑位 1：Node 版本过低
报错示例：
ERR_PNPM_UNSUPPORTED_ENGINE✅ 解决方案：
-
Node.js >= 18（推荐 18 LTS 或 20）
-
使用 nvm 管理版本：
nvm install 18
nvm use 18
坑位 2：pnpm install 卡死 / 网络超时
原因：国内访问 GitHub 慢。
✅ 解决方案：配置镜像源
pnpm config set registry https://registry.npmmirror.com
pnpm install坑位 3：playground 启动失败
有些同学会直接跑：
pnpm dev但 Vue3 仓库里并没有默认的 dev脚本。
✅ 正确方式：进入 playground
pnpm run dev --filter=playground或者：
cd packages/vue/examples/composition
pnpm dev四、Step 3：认识 Playground（调试神器）
Vue3 源码中自带了一个 playground，这是官方留给开发者调试用的。
路径：
packages/vue/examples/
├── composition # Composition API 示例
├── options-api # Options API 示例
└── ssr # SSR 示例启动 composition 示例：
cd packages/vue/examples/composition
pnpm dev打开浏览器：
http://localhost:5173你会看到一个最简单的 Vue3 页面。
📌 重点：
这个 playground 使用的是未打包的源码，并且自带 SourceMap。
五、Step 4：浏览器断点调试（入门）
打开 Chrome DevTools → Sources → core/packages
你会看到类似这样的路径：
core/packages/reactivity/src/reactive.ts试着在 reactive()函数里打一个断点：
export function reactive(target: object) {
// ⛔ 在这里打断点
if (isReadonly(target)) {
return target
}
return createReactiveObject(...)
}刷新页面，你会发现：
✅ 断点命中
✅ 变量可查看
✅ 调用栈清晰
局限性：
浏览器调试适合看"运行时行为"，但不适合做源码级单步跟踪。
六、Step 5：VSCode 断点调试（强烈推荐 ✅）
这才是读源码的正确姿势。
1️⃣ 创建调试配置
在项目根目录创建 .vscode/launch.json：
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug Vue3 Playground",
"type": "chrome",
"request": "launch",
"url": "http://localhost:5173",
"webRoot": "${workspaceFolder}",
"sourceMaps": true,
"sourceMapPathOverrides": {
"webpack://vue/*": "${workspaceFolder}/*"
}
}
]
}2️⃣ 启动调试
-
先启动 playground：
cd packages/vue/examples/composition pnpm dev -
在 VSCode 中按
F5，选择Debug Vue3 Playground -
在源码中打断点，例如：
// packages/reactivity/src/effect.ts
export function track(target, type, key) {
// ✅ 在这里打断点
if (!shouldTrack || activeEffect === undefined) {
return
}
...
}
✅ 现在你可以：
-
单步执行（F10 / F11）
-
查看调用栈
-
实时修改变量值
-
观察依赖收集过程
七、Step 6：写一个最小调试 Demo（实战）
打开：
packages/vue/examples/composition/index.html替换为以下内容：
<script src="../dist/vue.global.js"></script>
<div id="app">
{{ count }}
<button @click="increment">+1</button>
</div>
<script>
const { reactive, effect } = Vue
const state = reactive({
count: 0
})
effect(() => {
console.log('count changed:', state.count)
})
function increment() {
state.count++
}
Vue.createApp({
setup() {
return { increment }
}
}).mount('#app')
</script>然后在 effect.ts和 reactive.ts中打断点。
👉 你将亲眼看到：
-
reactive如何创建 Proxy -
effect如何被收集 -
state.count++如何触发trigger
八、调试技巧总结（工程向）
✅ 必会快捷键
| 功能 | Windows / Linux | macOS |
|---|---|---|
| 单步执行 | F10 | F10 |
| 单步进入 | F11 | F11 |
| 跳出 | Shift+F11 | Shift+F11 |
| 重启调试 | Ctrl+Shift+F5 | Cmd+Shift+F5 |
✅ 高效调试习惯
-
先看调用栈，再读代码
-
在关键函数入口打印参数
-
不要死磕一行代码，先抓主流程
-
结合单元测试理解源码
九、本篇小结
读完本篇，你已经完成了：
✅ Vue3 源码仓库克隆
✅ pnpm 环境配置（含避坑指南）
✅ Playground 启动
✅ VSCode + Chrome 断点调试
✅ 最小响应式 Demo 验证
一句话总结：
能打断点的源码，才是可读的源码。
十、下一篇预告
👉 《Vue3 源码详解（三）：响应式核心思想------从 Object.defineProperty 到 Proxy》
我们将从最小响应式实现 入手，手写一个 20 行的 mini-reactive，彻底搞懂 Vue3 响应式的本质。