简介Vue3 与 TypeScript 的工程实践资料包面向已掌握基础语法、希望从源码与实例层面理解 Composition API、响应式机制和类型系统的前端开发者。包内共 2002 个文件以 1042 个 Markdown 笔记和 803 个 JavaScript 源码及示例为主体辅以 147 个 JSON 配置与少量 HTML 测试页面压缩包约 63MB整体按主题分目录组织便于按模块检索。内容涵盖 Vue3 渲染性能优化要点、用 Composition API 组织与复用组件逻辑的方式以及在项目中通过 Interface、泛型与自定义类型约束数据结构、保证响应式数据准确性的做法同时延伸至 Vuex 与 Pinia 的状态集中管理、Vue Router 的页面导航组织以及 Ant Design Vue 等组件库的集成思路。已有 575 人学习适合想对照源码与笔记补齐工程化细节、提升类型安全意识的中级前端开发者。1. 先跑通再读码从 effect.ts 的断点开始而不是从第一行拿到一份 Vue3 TypeScript 的源码学习包最常见的翻车路径是从packages/reactivity/src/effect.ts第一行逐行往下读。读到track里那一堆分支开始走神合上电脑只剩一句“Proxy 拦截了 get”下次打开还是从头再来。这份资源的用法正好相反它用 TypeScript 的类型定义把响应式、编译器、运行时三块内容串起来先让你在一次真实的断点里看到依赖是怎么被收集、又是怎么被触发的再回头解释实现为什么必须这么写。它适合已经能用 Vue3 写业务、但说不清ref和reactive在类型层面为什么表现不一致的开发者如果连setup都没写过几遍直接读源码只会更糊涂。下面按“先能调试、再拆内核、最后验证”的顺序把它拆开。2. 包结构与构建链路把断点打进 src 而不是 dist读源码第一件体力活不是阅读而是让调试器停在你以为的那一行。我见过太多人对着dist里的压缩产物下断点看到的是变量名被替换成e、t、n的代码然后得出“源码没法调”的结论。源码包的价值恰恰在于它可以被构建成带 sourcemap 的产物再被一个几十行的复现脚本引用这样断点、调用栈、闭包变量全都能对上原始文件。第 2 章先把这条链路打通后面三章才有地方落脚。2.1 monorepo 的包边界决定你的阅读顺序这类资源通常是一个 workspace 仓库几十个源文件被拆进若干包包之间的依赖是一张单向图而不是网状。理解这张图比理解任何单个函数都重要因为它直接告诉你哪些包可以脱离浏览器单独跑哪些包必须和 DOM 绑在一起才能观察。包职责依赖方向建议投入reactivity响应式内核reactive / ref / effect / computed只依赖 shared第一优先2 到 3 天compiler-core模板 AST、转换阶段、代码生成依赖 shared第二优先runtime-core组件实例、渲染器、调度器依赖 reactivity、shared第三优先runtime-domDOM 平台实现、事件与属性 patch依赖 runtime-core按需查阅shared通用工具函数与 PatchFlags 常量无随用随查依赖方向决定了引入成本。reactivity的输入是一段普通对象输出是普通值不碰 DOM、不碰组件实例一个node脚本就能跑完一个完整流程所以它是唯一适合“单点打穿”的包。而runtime-core里的渲染器动辄两三千行它把响应式、虚拟节点 diff、调度队列压在同一段代码里新手直接啃必然迷路。我的建议是先在reactivity里把track/trigger的闭环看清楚再带着“渲染函数本质上是一个大的 effect”这个前提去读渲染器最后回头读编译器看模板怎么被翻译成那个 effect。还有一个容易被忽略的点聚合入口包vue并不是核心它只是把runtime-dom和compiler-dom拼到一起顺便做了一层兼容导出。很多人从这个入口往里追追三层还在转发函数耐心就耗光了。2.2 用 pnpm workspace 搭一个可断点的环境先把依赖装成和作者一致的状态再决定怎么构建。下面三条命令是这条链路的最小闭环顺序不要换。# 1) 按 lock 文件安装保证 workspace 内部包是软链而不是重复副本 pnpm install --frozen-lockfile # 2) 只构建需要的包并强制保留 sourcemap跳过压缩阶段 pnpm build reactivity runtime-core --sourcemap # 3) 用 node 跑一个最小复现脚本--inspect-brk 让进程停在第一行 node --inspect-brk ./scripts/min-repro.mjs--frozen-lockfile的作用是禁止安装过程改写 lock 文件避免你本地解析出的版本和作者不同从而读到一份“看起来一样、行为不一样”的代码。--sourcemap是整条链路的关键开关默认的生产构建会把 sourcemap 关掉或剥离断点只能落在 bundle 级别打开之后Chrome DevTools 或编辑器里的断点才会精确映射回.ts原文件。--inspect-brk和--inspect的差别在于前者会在第一行暂停给你时间把调试器挂上去否则脚本三秒跑完你什么都抓不到。复现脚本本身不用复杂只要能触发一次依赖收集和一次依赖触发就够。// scripts/min-repro.mjs —— 直接引用构建产物路径按仓库实际结构调整 import { reactive, effect } from ../packages/vue/dist/vue.runtime.esm-bundler.js const state reactive({ count: 0 }) // 在这里下断点观察全局 activeEffect 从 null 变成 ReactiveEffect 实例的瞬间 effect(() { console.log(run:, state.count) }) state.count // 断点应停在 trigger 内部取出依赖集合、逐个执行 effect.run这里选esm-bundler构建而不是 global 构建原因是 ESM 版本保留了模块边界调试器的调用栈会显示reactivity/src/effect.ts而不是一个匿名闭包global 构建把全部代码塞进一个立即执行函数sourcemap 的映射粒度会粗很多栈里经常只剩(anonymous)。文件名带bundler的那份还会把__DEV__之类的编译期开关留成可注入形式方便你在脚本里手动打开开发期警告很多“源码里明明有这段分支却没执行”的困惑就来源于这些开关。如果你用编辑器而不是浏览器调试还需要把模块路径指回源码否则右键“跳转到定义”永远落在.d.ts上。// tsconfig.json —— 让 tsserver 直接跳进 src而不是编译后的声明文件 { compilerOptions: { baseUrl: ., paths: { vue/reactivity: [packages/reactivity/src/index.ts], vue/runtime-core: [packages/runtime-core/src/index.ts] }, types: [node] } }baseUrl是paths生效的前提少了它整段配置静默失效。映射目标要写src/index.ts而不是dist/*.d.ts这是“能跳定义”和“只能看签名”的分水岭跳到src你能看到函数体、闭包和注释跳到.d.ts你只能看到类型。types: [node]是为了让process.env.NODE_ENV这类判断在编辑器里不报红源码里到处是这种守卫缺了它满屏波浪线很容易误以为自己改坏了什么。2.3 从单测入口进比从 index.ts 进快得多每个包下面通常都有__tests__目录一个*.spec.ts就是一份带断言的最小复现作者已经帮你把边界条件写好了。与其自己构造场景不如直接跑别人写好的用例再把断点打进去。# 只跑 effect 相关的用例-t 按用例名过滤避免整个文件几百个 case 一起跑 pnpm vitest run packages/reactivity/__tests__/effect.spec.ts -t should run # 需要停在用例内部时把调试端口透传给 node node --inspect-brk ./node_modules/vitest/vitest.mjs run packages/reactivity/__tests__/effect.spec.tsrun表示非 watch 模式跑完就退出适合配合断点不加run会进入监听状态断点触发一次之后进程还挂着容易误判“代码没执行”。-t的匹配是按用例名做子串匹配所以名字要写够独特写should会把大半个文件都拉起来断点被无关用例反复命中调试体验极差。提示单测文件里的断言本身就是结论。先读断言知道这段代码“应该产出什么”再进实现看“怎么产出”比反过来省一半时间。3. 响应式内核40 行骨架与泛型签名的对应关系响应式是整份资源里最值得投入的部分因为它的结构极其干净一个存储依赖的容器、一个记录当前正在执行的副作用、两个动作收集与触发。难点不在算法而在 TypeScript 的类型签名——ref的.value为什么在模板里不用写、reactive返回的类型为什么把嵌套的ref全部摊平这些看起来玄学的东西答案都在类型定义里而不是在运行时逻辑里。3.1 用 40 行复刻 track / trigger 的闭环在打开源码之前先自己写一遍骨架。写完再对照你会发现差异主要在边界处理上主干逻辑几乎一致。// mini-reactive.ts —— 只保留主干用来对照源码结构 type Dep SetReactiveEffect const targetMap new WeakMapobject, MapPropertyKey, Dep() let activeEffect: ReactiveEffect | undefined class ReactiveEffect { constructor(public fn: () void) {} run() { activeEffect this // 进入时把自己挂成当前副作用 try { return this.fn() // 执行期间所有 get 都会被 track 捕获 } finally { activeEffect undefined // 必须还原否则嵌套 effect 会串味 } } } function track(target: object, key: PropertyKey) { if (!activeEffect) return // 不在任何 effect 里读属性直接跳过 let depsMap targetMap.get(target) if (!depsMap) targetMap.set(target, (depsMap new Map())) let dep depsMap.get(key) if (!dep) depsMap.set(key, (dep new Set())) dep.add(activeEffect) // 建立 key - effect 的反向索引 } function trigger(target: object, key: PropertyKey) { const dep targetMap.get(target)?.get(key) if (!dep) return dep.forEach(effect effect.run()) // 简化版不做调度、不去重、不判自触发 } function reactiveT extends object(target: T): T { return new Proxy(target, { get(obj, key, receiver) { track(obj, key) return Reflect.get(obj, key, receiver) }, set(obj, key, value, receiver) { const ok Reflect.set(obj, key, value, receiver) trigger(obj, key) return ok } }) }这段骨架里有三个设计点值得盯着看。第一是WeakMap套Map套Set的三层结构最外层用WeakMap是为了让被代理对象被回收时依赖表跟着释放如果用Map一个临时对象只要被 effect 读过一次就永远留在内存里。第二是try / finally里对activeEffect的还原真实实现用的是副作用栈而不是单个变量因为effect内部再嵌套effect时内层执行完必须回到外层的“当前副作用”单变量做不到这一点。第三是trigger里的省略项真实实现要处理调度器scheduler、要避免 effect 在执行中再次触发自己导致死循环、还要按effect ! activeEffect做过滤这三件事加起来就是骨架和源码之间那一百多行的差距。参数层面需要留意的只有run的返回值。骨架里返回了this.fn()的结果真实实现同样如此因为computed依赖这个返回值做缓存如果你在改造时把它丢了computed那部分读起来就会莫名其妙。3.2 ref 与 reactive 的类型签名差在哪运行时上ref和reactive是两套实现前者包一个RefImpl实例用访问器属性value做拦截后者用Proxy拦截整个对象。但真正让人困惑的是类型因为类型决定了你在编辑器里看到的行为而编辑器里的行为和运行时并不总是一一对应。// 摘自声明文件的结构用于对照理解非完整定义 interface RefT any { value: T } type UnwrapRefT T extends Refinfer V ? UnwrapRefSimpleV : T extends object ? { [K in keyof T]: UnwrapRefT[K] } : T function refT(value: T): RefUnwrapRefT function reactiveT extends object(target: T): UnwrapNestedRefsTRefT里只有一个value属性这是它能被自动解包的前提模板编译时会把count改写成count.value编译器只需要判断“这个标识符的类型是不是带value的引用类型”。而reactive返回的是UnwrapNestedRefsT这个类型工具做的事情是递归地把对象内部所有Ref摊平成它包裹的原始类型所以reactive({ n: ref(0) })之后state.n是number而不是Refnumber因为读取n时 Proxy 的get里做了isRef(res) ? res.value : res的判断。这里有个反直觉的地方reactive的类型摊平是递归的但递归在循环引用处会出问题类型系统没法无限展开一个自我引用的结构真实实现里用了一组UnwrapRefSimple、BaseTypes、Builtin的分支把数组、Map、Set、Date 这些内置类型挡在递归之外。读这段类型定义时不要试图一次看懂全部条件分支正确的姿势是拿一个具体例子去试写const s reactive({ a: ref(1), b: { c: ref() } })把鼠标悬停在s上看推导出来的展开类型再回类型定义里找是哪个分支命中的。shallowRef与ref的签名几乎一样差别只在返回值不递归解包readonly走的是DeepReadonlyT它把每一层都加上readonly修饰。这几个类型工具放在一起看能很直观地理解“运行时做多少类型就描述多少”这个原则。3.3 用类型报错反查实现路径类型不只是文档它还是一把探针。把错误的类型传进去编译器报错的位置会直接告诉你实现走了哪条分支。import { reactive, readonly, shallowRef } from vue/reactivity const raw { nested: { count: 1 } } const state readonly(raw) // 报错无法为只读属性赋值 —— 说明 DeepReadonly 已经递归到了 nested 这一层 state.nested.count 2 // 报错Ref{ count: number } 上不存在 value 之外的属性 const s shallowRef({ count: 1 }) s.count第一条报错能验证readonly的递归深度如果只在外层加readonlystate.nested.count 2不会报错所以报错本身就证明了实现确实做了深度遍历运行时的readonly同样是深层 Proxy两者是对齐的。第二条报错说明shallowRef不会像ref那样把对象内部再包一层.value拿到的是原对象这也解释了为什么给shallowRef传一个大对象时性能更好——它只代理了value这一个访问器。我一般的做法是每读完一个类型工具就故意写一段会报错的代码把报错信息抄到笔记里。等下次业务里遇到“为什么这里推导出来是any”翻笔记往往比翻源码快。4. 编译器与运行时的衔接模板表达式怎么变成可推导的类型响应式解决的是“数据变了怎么通知”编译器解决的是“模板怎么写才能变成通知数据的代码”。这两块在源码里是分开的两个包但在实际运行时会合流编译产物里读的每一个响应式属性都会变成一次track。把这条线打通你才算真正看懂了“模板里写个变量页面就会更新”这句话。4.1 parse / transform / generate 三段式在源码里的落点编译器主干是三个纯函数输入输出都是数据结构没有副作用非常适合单独调用观察。// compile-demo.ts —— 直接把模板编译成渲染函数源码字符串 import { compile } from vue/compiler-dom const { code, ast } compile( div :iduid{{ msg }}/div, { mode: module, // 生成 ESM 导出而不是 new Function 的字符串 prefixIdentifiers: true, // 模板表达式里的变量加 _ctx. 前缀 hoistStatic: true // 开启静态节点提升 } ) console.log(code)mode: module决定产物形态function模式生成一段可以被new Function直接执行的字符串module模式生成标准的 ESM 代码后者可以被打包工具继续处理也是现代构建链路上的默认选择。prefixIdentifiers: true会让模板里的msg变成_ctx.msg这一步是把“模板作用域”翻译成“JavaScript 作用域”的关键没有它编译产物里的变量名和组件实例对不上运行时根本拿不到值。hoistStatic: true会把纯静态的节点提到渲染函数外面只创建一次这是性能优化里最直观的一条。三段式的边界很清晰parse只做词法和语法分析产出一棵模板 AST节点类型用数字常量标记元素、文本、插值、指令各占一个transform遍历 AST插件式地往节点上挂codegenNode静态提升、指令转换、v-if分支合并都在这一步generate只负责把codegenNode拼成字符串它不判断语义。读源码时如果发现某个逻辑“不知道该归哪一段”先看它是在修改 AST 还是在拼字符串答案立刻就出来了。ast这个返回值值得单独调试一次。把ast打印出来你会看到每个元素节点上挂着props、children、locloc里记录了源码的起止位置和行列号——这就是开发环境下模板报错能精确指到你写的第几行的原因。4.2 静态提升与 patchFlag 是怎么判定的编译器在transform阶段给动态节点打上patchFlag运行时 diff 靠这个数字决定“要不要比较这个节点的子内容”。理解这套标记等于理解了 diff 的性能边界。标记含义运行时行为TEXT只有文本内容是动态的只比对文本跳过属性CLASSclass 是动态的只比对 classPROPS有动态属性但无动态 key走完整 props 比对FULL_PROPS存在动态 key 的属性无法静态优化全量比对NEED_PATCH需要走 patch 流程调用对应元素的 patch 方法DYNAMIC_SLOTS插槽内容动态跳过静态插槽优化标记会在相邻位上进行按位或运算组合所以一个节点可能同时带TEXT | CLASS。判定逻辑在transform的各个插件里分析属性的绑定类型能静态确定的值不打标记v-bindobj这种展开写法直接给FULL_PROPS。有一个容易踩的边界div :ida :classb和div v-bindobj的优化结果完全不同前者能精确到单个属性后者只能全量比对——这也是为什么在性能敏感的长列表里展开写法要慎用。4.3 模板类型检查工具拿到的到底是什么TypeScript 本身不认识模板.vue文件里的template对tsc来说就是一段普通标签。模板类型检查工具的做法是把模板编译成一段虚拟的 TypeScript 代码再交给tsc做类型推导报错时通过位置映射把错误信息还原到模板的行列上。// 虚拟文件的大致形态帮助理解类型从哪来 const _component { props: { msg: { type: String as PropTypestring, required: true } }, setup(__props: { msg: string }) { return (_ctx: any, _cache: any) { // 模板里写 {{ msg }}这里读的就是 __props.msg类型来自上面的 PropType return msg } } }所以defineProps{ msg: string }()能推导出模板里的msg是string靠的不是什么魔法而是宏被编译成了带泛型参数的函数调用类型沿调用链传下去。反过来如果你在模板里访问一个setup没返回、props也没声明的变量报错信息会指向虚拟文件的位置看起来像一个不存在的文件——这是正常的别去找那个文件去看模板里对应的表达式即可。注意模板类型检查依赖编译期生成的元信息v-for里变量的类型、作用域插槽的参数类型都在这层生成。如果某个变量的类型莫名其妙变成any八成是编译阶段没能把它识别成绑定而不是类型工具本身有问题。5. 避坑与排查读这份源码时最容易翻车的五个点这一节全是血泪经验每条都对应一个真实发生过的翻车现场。读源码的成本大部分不在理解而在这些看起来像环境问题、实际是认知偏差的地方。现象断点打上去是空心圆提示 “Breakpoint set but not yet bound”。原因编辑器把断点打在了.ts源文件上但 node 实际执行的是构建产物sourcemap 没有生成或被关闭了映射链断了。 解决确认构建命令里带了--sourcemap检查产物同目录下是否存在.map文件如果用的是 node 直接跑脚本加--enable-source-maps让 node 加载映射表否则 node 自己不会去读.map。现象改了源码里的console.log重新跑脚本毫无反应。原因脚本import的是dist里的构建产物改src不改产物等于没改workspace 的软链让node_modules里那份看起来像源码其实是构建输出。 解决要么每次改完重跑构建观察模式下用tsc -w或构建工具的 watch要么在调试阶段直接用路径别名把 import 指向src/index.ts让运行时直接加载 TS需要ts-node或带 TS 转译的加载器。现象reactive对象解构之后页面不更新了。原因track建立的依赖是挂在target key上的解构const { count } state只是把当前值读出来赋给一个普通变量后续count的读取完全不经过 Proxy自然不会触发依赖收集。 解决从源码角度理解之后业务上的处理是保持对象调用或者用toRefs/toRef把属性转成带get value的引用toRefs的实现就是给每个 key 建一个访问器读的时候仍然回到原对象所以链路没断。现象在effect里读了ref.value修改ref.value却不触发。原因RefImpl的依赖挂在dep这个独立集合上和reactive的targetMap是两套存储如果你读的是shallowRef内部的嵌套对象属性那个属性压根没被代理属于“读了个寂寞”。 解决先确认读的是.value而不是对象本身再确认这个 ref 是不是shallowRef。调试时分别对RefImpl的get value和set value下断点看哪一侧没进。现象照着文档看编译产物和自己跑出来的代码对不上。原因compile的mode、prefixIdentifiers、hoistStatic三个选项组合会产生差异极大的输出文档示例通常省略了选项说明另外不同版本的编译产物在patchFlag命名上也有调整。 解决调用compile时把选项显式写全并且在调试脚本里打印code的原始字符串而不是格式化后的版本判断逻辑差异时以你自己跑出来的产物为准别硬套记忆里的示例。6. 进阶验证用最小复现加单测把结论钉死读到第 5 章容易产生一种“我都懂了”的错觉。检验方式只有一个把结论写成断言跑通它。我一般的套路是三级验证越往后越硬。验证层级做法能证明什么打印观察在关键函数里打日志、断点看闭包代码路径走没走通最小复现单独写脚本引用源码构造单一场景结论是否依赖具体环境单测断言用测试框架跑断言执行次数和结果结论是否稳定、可回归打印观察最省事但它证明不了稳定性——你看到一次正确的执行顺序可能是因为这次恰好没有并发也可能是因为你手动改了某处状态。最小复现把它往前推一步脱离业务代码只留必要输入。单测断言是最后一层它把“我看到”变成“它必须”以后改源码、换版本跑一遍就知道有没有被破坏。下面这段断言是我验证track次数时用的模板核心是数“副作用执行了几次”而不是数日志。import { describe, it, expect, vi } from vitest import { reactive, effect, stop } from vue/reactivity describe(effect 的依赖收集边界, () { it(只读取一个属性时修改其它属性不应触发重跑, () { const state reactive({ a: 1, b: 2 }) const spy vi.fn(() state.a) // 只访问 a const runner effect(spy) expect(spy).toHaveBeenCalledTimes(1) // 首次执行 state.b // 访问 b 不等于收集了 b expect(spy).toHaveBeenCalledTimes(1) state.a // 访问过 a才会被触发 expect(spy).toHaveBeenCalledTimes(2) stop(runner) // 手工停止验证依赖已被清理 state.a expect(spy).toHaveBeenCalledTimes(2) }) })这段断言的关键在最后三行stop之后spy的调用次数不再增长说明依赖集合里的这个 effect 被移除了。如果你手上的版本在stop之后仍然触发那大概率是清理逻辑的分支和你读的那段源码不是同一版本——这就是单测的价值它逼你去确认版本而不是凭记忆下结论。还有一个小技巧验证分支覆盖时用state.b这类“读了但没改对”的操作比直接改a更能暴露问题。trigger在找不到对应依赖集合时应当直接返回如果它误触发了整个 target 的所有依赖第一次state.b就会让spy多跑一次。很多人读完源码觉得“这里肯定有判断”但从来没验证过判断真的生效。最后说一个我自己踩过的坑。我早期读源码有个坏习惯看到优化分支就跳过只读主流程觉得“优化不影响理解”。结果在一次排查里我笃定某个属性变更会触发重渲染实际却没触发查了半天才发现是编译期打了patchFlag运行时只比对了文本属性压根没进 diff 流程。从那以后我每次对某个结论有把握的时候都强制走一遍“类型检查 单测断言”这两步把“我觉得”换成“它必须”。源码学习资源真正的价值不在于它写得多全而在于它给了你一套可以反复验证的结构你照着跑通的每一条断言都是以后排查线上问题的后悔药。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/26 3:51:57 · 阅读 1.2k Vue3+TS源码学习：调试链路、响应式内核与编译器验证
简介Vue3 与 TypeScript 的工程实践资料包面向已掌握基础语法、希望从源码与实例层面理解 Composition API、响应式机制和类型系统的前端开发者。包内共 2002 个文件以 1042 个 Markdown 笔记和 803 个 JavaScript 源码及示例为主体辅以 147 个 JSON 配置与少量 HTML 测试页面压缩包约 63MB整体按主题分目录组织便于按模块检索。内容涵盖 Vue3 渲染性能优化要点、用 Composition API 组织与复用组件逻辑的方式以及在项目中通过 Interface、泛型与自定义类型约束数据结构、保证响应式数据准确性的做法同时延伸至 Vuex 与 Pinia 的状态集中管理、Vue Router 的页面导航组织以及 Ant Design Vue 等组件库的集成思路。已有 575 人学习适合想对照源码与笔记补齐工程化细节、提升类型安全意识的中级前端开发者。1. 先跑通再读码从 effect.ts 的断点开始而不是从第一行拿到一份 Vue3 TypeScript 的源码学习包最常见的翻车路径是从packages/reactivity/src/effect.ts第一行逐行往下读。读到track里那一堆分支开始走神合上电脑只剩一句“Proxy 拦截了 get”下次打开还是从头再来。这份资源的用法正好相反它用 TypeScript 的类型定义把响应式、编译器、运行时三块内容串起来先让你在一次真实的断点里看到依赖是怎么被收集、又是怎么被触发的再回头解释实现为什么必须这么写。它适合已经能用 Vue3 写业务、但说不清ref和reactive在类型层面为什么表现不一致的开发者如果连setup都没写过几遍直接读源码只会更糊涂。下面按“先能调试、再拆内核、最后验证”的顺序把它拆开。2. 包结构与构建链路把断点打进 src 而不是 dist读源码第一件体力活不是阅读而是让调试器停在你以为的那一行。我见过太多人对着dist里的压缩产物下断点看到的是变量名被替换成e、t、n的代码然后得出“源码没法调”的结论。源码包的价值恰恰在于它可以被构建成带 sourcemap 的产物再被一个几十行的复现脚本引用这样断点、调用栈、闭包变量全都能对上原始文件。第 2 章先把这条链路打通后面三章才有地方落脚。2.1 monorepo 的包边界决定你的阅读顺序这类资源通常是一个 workspace 仓库几十个源文件被拆进若干包包之间的依赖是一张单向图而不是网状。理解这张图比理解任何单个函数都重要因为它直接告诉你哪些包可以脱离浏览器单独跑哪些包必须和 DOM 绑在一起才能观察。包职责依赖方向建议投入reactivity响应式内核reactive / ref / effect / computed只依赖 shared第一优先2 到 3 天compiler-core模板 AST、转换阶段、代码生成依赖 shared第二优先runtime-core组件实例、渲染器、调度器依赖 reactivity、shared第三优先runtime-domDOM 平台实现、事件与属性 patch依赖 runtime-core按需查阅shared通用工具函数与 PatchFlags 常量无随用随查依赖方向决定了引入成本。reactivity的输入是一段普通对象输出是普通值不碰 DOM、不碰组件实例一个node脚本就能跑完一个完整流程所以它是唯一适合“单点打穿”的包。而runtime-core里的渲染器动辄两三千行它把响应式、虚拟节点 diff、调度队列压在同一段代码里新手直接啃必然迷路。我的建议是先在reactivity里把track/trigger的闭环看清楚再带着“渲染函数本质上是一个大的 effect”这个前提去读渲染器最后回头读编译器看模板怎么被翻译成那个 effect。还有一个容易被忽略的点聚合入口包vue并不是核心它只是把runtime-dom和compiler-dom拼到一起顺便做了一层兼容导出。很多人从这个入口往里追追三层还在转发函数耐心就耗光了。2.2 用 pnpm workspace 搭一个可断点的环境先把依赖装成和作者一致的状态再决定怎么构建。下面三条命令是这条链路的最小闭环顺序不要换。# 1) 按 lock 文件安装保证 workspace 内部包是软链而不是重复副本 pnpm install --frozen-lockfile # 2) 只构建需要的包并强制保留 sourcemap跳过压缩阶段 pnpm build reactivity runtime-core --sourcemap # 3) 用 node 跑一个最小复现脚本--inspect-brk 让进程停在第一行 node --inspect-brk ./scripts/min-repro.mjs--frozen-lockfile的作用是禁止安装过程改写 lock 文件避免你本地解析出的版本和作者不同从而读到一份“看起来一样、行为不一样”的代码。--sourcemap是整条链路的关键开关默认的生产构建会把 sourcemap 关掉或剥离断点只能落在 bundle 级别打开之后Chrome DevTools 或编辑器里的断点才会精确映射回.ts原文件。--inspect-brk和--inspect的差别在于前者会在第一行暂停给你时间把调试器挂上去否则脚本三秒跑完你什么都抓不到。复现脚本本身不用复杂只要能触发一次依赖收集和一次依赖触发就够。// scripts/min-repro.mjs —— 直接引用构建产物路径按仓库实际结构调整 import { reactive, effect } from ../packages/vue/dist/vue.runtime.esm-bundler.js const state reactive({ count: 0 }) // 在这里下断点观察全局 activeEffect 从 null 变成 ReactiveEffect 实例的瞬间 effect(() { console.log(run:, state.count) }) state.count // 断点应停在 trigger 内部取出依赖集合、逐个执行 effect.run这里选esm-bundler构建而不是 global 构建原因是 ESM 版本保留了模块边界调试器的调用栈会显示reactivity/src/effect.ts而不是一个匿名闭包global 构建把全部代码塞进一个立即执行函数sourcemap 的映射粒度会粗很多栈里经常只剩(anonymous)。文件名带bundler的那份还会把__DEV__之类的编译期开关留成可注入形式方便你在脚本里手动打开开发期警告很多“源码里明明有这段分支却没执行”的困惑就来源于这些开关。如果你用编辑器而不是浏览器调试还需要把模块路径指回源码否则右键“跳转到定义”永远落在.d.ts上。// tsconfig.json —— 让 tsserver 直接跳进 src而不是编译后的声明文件 { compilerOptions: { baseUrl: ., paths: { vue/reactivity: [packages/reactivity/src/index.ts], vue/runtime-core: [packages/runtime-core/src/index.ts] }, types: [node] } }baseUrl是paths生效的前提少了它整段配置静默失效。映射目标要写src/index.ts而不是dist/*.d.ts这是“能跳定义”和“只能看签名”的分水岭跳到src你能看到函数体、闭包和注释跳到.d.ts你只能看到类型。types: [node]是为了让process.env.NODE_ENV这类判断在编辑器里不报红源码里到处是这种守卫缺了它满屏波浪线很容易误以为自己改坏了什么。2.3 从单测入口进比从 index.ts 进快得多每个包下面通常都有__tests__目录一个*.spec.ts就是一份带断言的最小复现作者已经帮你把边界条件写好了。与其自己构造场景不如直接跑别人写好的用例再把断点打进去。# 只跑 effect 相关的用例-t 按用例名过滤避免整个文件几百个 case 一起跑 pnpm vitest run packages/reactivity/__tests__/effect.spec.ts -t should run # 需要停在用例内部时把调试端口透传给 node node --inspect-brk ./node_modules/vitest/vitest.mjs run packages/reactivity/__tests__/effect.spec.tsrun表示非 watch 模式跑完就退出适合配合断点不加run会进入监听状态断点触发一次之后进程还挂着容易误判“代码没执行”。-t的匹配是按用例名做子串匹配所以名字要写够独特写should会把大半个文件都拉起来断点被无关用例反复命中调试体验极差。提示单测文件里的断言本身就是结论。先读断言知道这段代码“应该产出什么”再进实现看“怎么产出”比反过来省一半时间。3. 响应式内核40 行骨架与泛型签名的对应关系响应式是整份资源里最值得投入的部分因为它的结构极其干净一个存储依赖的容器、一个记录当前正在执行的副作用、两个动作收集与触发。难点不在算法而在 TypeScript 的类型签名——ref的.value为什么在模板里不用写、reactive返回的类型为什么把嵌套的ref全部摊平这些看起来玄学的东西答案都在类型定义里而不是在运行时逻辑里。3.1 用 40 行复刻 track / trigger 的闭环在打开源码之前先自己写一遍骨架。写完再对照你会发现差异主要在边界处理上主干逻辑几乎一致。// mini-reactive.ts —— 只保留主干用来对照源码结构 type Dep SetReactiveEffect const targetMap new WeakMapobject, MapPropertyKey, Dep() let activeEffect: ReactiveEffect | undefined class ReactiveEffect { constructor(public fn: () void) {} run() { activeEffect this // 进入时把自己挂成当前副作用 try { return this.fn() // 执行期间所有 get 都会被 track 捕获 } finally { activeEffect undefined // 必须还原否则嵌套 effect 会串味 } } } function track(target: object, key: PropertyKey) { if (!activeEffect) return // 不在任何 effect 里读属性直接跳过 let depsMap targetMap.get(target) if (!depsMap) targetMap.set(target, (depsMap new Map())) let dep depsMap.get(key) if (!dep) depsMap.set(key, (dep new Set())) dep.add(activeEffect) // 建立 key - effect 的反向索引 } function trigger(target: object, key: PropertyKey) { const dep targetMap.get(target)?.get(key) if (!dep) return dep.forEach(effect effect.run()) // 简化版不做调度、不去重、不判自触发 } function reactiveT extends object(target: T): T { return new Proxy(target, { get(obj, key, receiver) { track(obj, key) return Reflect.get(obj, key, receiver) }, set(obj, key, value, receiver) { const ok Reflect.set(obj, key, value, receiver) trigger(obj, key) return ok } }) }这段骨架里有三个设计点值得盯着看。第一是WeakMap套Map套Set的三层结构最外层用WeakMap是为了让被代理对象被回收时依赖表跟着释放如果用Map一个临时对象只要被 effect 读过一次就永远留在内存里。第二是try / finally里对activeEffect的还原真实实现用的是副作用栈而不是单个变量因为effect内部再嵌套effect时内层执行完必须回到外层的“当前副作用”单变量做不到这一点。第三是trigger里的省略项真实实现要处理调度器scheduler、要避免 effect 在执行中再次触发自己导致死循环、还要按effect ! activeEffect做过滤这三件事加起来就是骨架和源码之间那一百多行的差距。参数层面需要留意的只有run的返回值。骨架里返回了this.fn()的结果真实实现同样如此因为computed依赖这个返回值做缓存如果你在改造时把它丢了computed那部分读起来就会莫名其妙。3.2 ref 与 reactive 的类型签名差在哪运行时上ref和reactive是两套实现前者包一个RefImpl实例用访问器属性value做拦截后者用Proxy拦截整个对象。但真正让人困惑的是类型因为类型决定了你在编辑器里看到的行为而编辑器里的行为和运行时并不总是一一对应。// 摘自声明文件的结构用于对照理解非完整定义 interface RefT any { value: T } type UnwrapRefT T extends Refinfer V ? UnwrapRefSimpleV : T extends object ? { [K in keyof T]: UnwrapRefT[K] } : T function refT(value: T): RefUnwrapRefT function reactiveT extends object(target: T): UnwrapNestedRefsTRefT里只有一个value属性这是它能被自动解包的前提模板编译时会把count改写成count.value编译器只需要判断“这个标识符的类型是不是带value的引用类型”。而reactive返回的是UnwrapNestedRefsT这个类型工具做的事情是递归地把对象内部所有Ref摊平成它包裹的原始类型所以reactive({ n: ref(0) })之后state.n是number而不是Refnumber因为读取n时 Proxy 的get里做了isRef(res) ? res.value : res的判断。这里有个反直觉的地方reactive的类型摊平是递归的但递归在循环引用处会出问题类型系统没法无限展开一个自我引用的结构真实实现里用了一组UnwrapRefSimple、BaseTypes、Builtin的分支把数组、Map、Set、Date 这些内置类型挡在递归之外。读这段类型定义时不要试图一次看懂全部条件分支正确的姿势是拿一个具体例子去试写const s reactive({ a: ref(1), b: { c: ref() } })把鼠标悬停在s上看推导出来的展开类型再回类型定义里找是哪个分支命中的。shallowRef与ref的签名几乎一样差别只在返回值不递归解包readonly走的是DeepReadonlyT它把每一层都加上readonly修饰。这几个类型工具放在一起看能很直观地理解“运行时做多少类型就描述多少”这个原则。3.3 用类型报错反查实现路径类型不只是文档它还是一把探针。把错误的类型传进去编译器报错的位置会直接告诉你实现走了哪条分支。import { reactive, readonly, shallowRef } from vue/reactivity const raw { nested: { count: 1 } } const state readonly(raw) // 报错无法为只读属性赋值 —— 说明 DeepReadonly 已经递归到了 nested 这一层 state.nested.count 2 // 报错Ref{ count: number } 上不存在 value 之外的属性 const s shallowRef({ count: 1 }) s.count第一条报错能验证readonly的递归深度如果只在外层加readonlystate.nested.count 2不会报错所以报错本身就证明了实现确实做了深度遍历运行时的readonly同样是深层 Proxy两者是对齐的。第二条报错说明shallowRef不会像ref那样把对象内部再包一层.value拿到的是原对象这也解释了为什么给shallowRef传一个大对象时性能更好——它只代理了value这一个访问器。我一般的做法是每读完一个类型工具就故意写一段会报错的代码把报错信息抄到笔记里。等下次业务里遇到“为什么这里推导出来是any”翻笔记往往比翻源码快。4. 编译器与运行时的衔接模板表达式怎么变成可推导的类型响应式解决的是“数据变了怎么通知”编译器解决的是“模板怎么写才能变成通知数据的代码”。这两块在源码里是分开的两个包但在实际运行时会合流编译产物里读的每一个响应式属性都会变成一次track。把这条线打通你才算真正看懂了“模板里写个变量页面就会更新”这句话。4.1 parse / transform / generate 三段式在源码里的落点编译器主干是三个纯函数输入输出都是数据结构没有副作用非常适合单独调用观察。// compile-demo.ts —— 直接把模板编译成渲染函数源码字符串 import { compile } from vue/compiler-dom const { code, ast } compile( div :iduid{{ msg }}/div, { mode: module, // 生成 ESM 导出而不是 new Function 的字符串 prefixIdentifiers: true, // 模板表达式里的变量加 _ctx. 前缀 hoistStatic: true // 开启静态节点提升 } ) console.log(code)mode: module决定产物形态function模式生成一段可以被new Function直接执行的字符串module模式生成标准的 ESM 代码后者可以被打包工具继续处理也是现代构建链路上的默认选择。prefixIdentifiers: true会让模板里的msg变成_ctx.msg这一步是把“模板作用域”翻译成“JavaScript 作用域”的关键没有它编译产物里的变量名和组件实例对不上运行时根本拿不到值。hoistStatic: true会把纯静态的节点提到渲染函数外面只创建一次这是性能优化里最直观的一条。三段式的边界很清晰parse只做词法和语法分析产出一棵模板 AST节点类型用数字常量标记元素、文本、插值、指令各占一个transform遍历 AST插件式地往节点上挂codegenNode静态提升、指令转换、v-if分支合并都在这一步generate只负责把codegenNode拼成字符串它不判断语义。读源码时如果发现某个逻辑“不知道该归哪一段”先看它是在修改 AST 还是在拼字符串答案立刻就出来了。ast这个返回值值得单独调试一次。把ast打印出来你会看到每个元素节点上挂着props、children、locloc里记录了源码的起止位置和行列号——这就是开发环境下模板报错能精确指到你写的第几行的原因。4.2 静态提升与 patchFlag 是怎么判定的编译器在transform阶段给动态节点打上patchFlag运行时 diff 靠这个数字决定“要不要比较这个节点的子内容”。理解这套标记等于理解了 diff 的性能边界。标记含义运行时行为TEXT只有文本内容是动态的只比对文本跳过属性CLASSclass 是动态的只比对 classPROPS有动态属性但无动态 key走完整 props 比对FULL_PROPS存在动态 key 的属性无法静态优化全量比对NEED_PATCH需要走 patch 流程调用对应元素的 patch 方法DYNAMIC_SLOTS插槽内容动态跳过静态插槽优化标记会在相邻位上进行按位或运算组合所以一个节点可能同时带TEXT | CLASS。判定逻辑在transform的各个插件里分析属性的绑定类型能静态确定的值不打标记v-bindobj这种展开写法直接给FULL_PROPS。有一个容易踩的边界div :ida :classb和div v-bindobj的优化结果完全不同前者能精确到单个属性后者只能全量比对——这也是为什么在性能敏感的长列表里展开写法要慎用。4.3 模板类型检查工具拿到的到底是什么TypeScript 本身不认识模板.vue文件里的template对tsc来说就是一段普通标签。模板类型检查工具的做法是把模板编译成一段虚拟的 TypeScript 代码再交给tsc做类型推导报错时通过位置映射把错误信息还原到模板的行列上。// 虚拟文件的大致形态帮助理解类型从哪来 const _component { props: { msg: { type: String as PropTypestring, required: true } }, setup(__props: { msg: string }) { return (_ctx: any, _cache: any) { // 模板里写 {{ msg }}这里读的就是 __props.msg类型来自上面的 PropType return msg } } }所以defineProps{ msg: string }()能推导出模板里的msg是string靠的不是什么魔法而是宏被编译成了带泛型参数的函数调用类型沿调用链传下去。反过来如果你在模板里访问一个setup没返回、props也没声明的变量报错信息会指向虚拟文件的位置看起来像一个不存在的文件——这是正常的别去找那个文件去看模板里对应的表达式即可。注意模板类型检查依赖编译期生成的元信息v-for里变量的类型、作用域插槽的参数类型都在这层生成。如果某个变量的类型莫名其妙变成any八成是编译阶段没能把它识别成绑定而不是类型工具本身有问题。5. 避坑与排查读这份源码时最容易翻车的五个点这一节全是血泪经验每条都对应一个真实发生过的翻车现场。读源码的成本大部分不在理解而在这些看起来像环境问题、实际是认知偏差的地方。现象断点打上去是空心圆提示 “Breakpoint set but not yet bound”。原因编辑器把断点打在了.ts源文件上但 node 实际执行的是构建产物sourcemap 没有生成或被关闭了映射链断了。 解决确认构建命令里带了--sourcemap检查产物同目录下是否存在.map文件如果用的是 node 直接跑脚本加--enable-source-maps让 node 加载映射表否则 node 自己不会去读.map。现象改了源码里的console.log重新跑脚本毫无反应。原因脚本import的是dist里的构建产物改src不改产物等于没改workspace 的软链让node_modules里那份看起来像源码其实是构建输出。 解决要么每次改完重跑构建观察模式下用tsc -w或构建工具的 watch要么在调试阶段直接用路径别名把 import 指向src/index.ts让运行时直接加载 TS需要ts-node或带 TS 转译的加载器。现象reactive对象解构之后页面不更新了。原因track建立的依赖是挂在target key上的解构const { count } state只是把当前值读出来赋给一个普通变量后续count的读取完全不经过 Proxy自然不会触发依赖收集。 解决从源码角度理解之后业务上的处理是保持对象调用或者用toRefs/toRef把属性转成带get value的引用toRefs的实现就是给每个 key 建一个访问器读的时候仍然回到原对象所以链路没断。现象在effect里读了ref.value修改ref.value却不触发。原因RefImpl的依赖挂在dep这个独立集合上和reactive的targetMap是两套存储如果你读的是shallowRef内部的嵌套对象属性那个属性压根没被代理属于“读了个寂寞”。 解决先确认读的是.value而不是对象本身再确认这个 ref 是不是shallowRef。调试时分别对RefImpl的get value和set value下断点看哪一侧没进。现象照着文档看编译产物和自己跑出来的代码对不上。原因compile的mode、prefixIdentifiers、hoistStatic三个选项组合会产生差异极大的输出文档示例通常省略了选项说明另外不同版本的编译产物在patchFlag命名上也有调整。 解决调用compile时把选项显式写全并且在调试脚本里打印code的原始字符串而不是格式化后的版本判断逻辑差异时以你自己跑出来的产物为准别硬套记忆里的示例。6. 进阶验证用最小复现加单测把结论钉死读到第 5 章容易产生一种“我都懂了”的错觉。检验方式只有一个把结论写成断言跑通它。我一般的套路是三级验证越往后越硬。验证层级做法能证明什么打印观察在关键函数里打日志、断点看闭包代码路径走没走通最小复现单独写脚本引用源码构造单一场景结论是否依赖具体环境单测断言用测试框架跑断言执行次数和结果结论是否稳定、可回归打印观察最省事但它证明不了稳定性——你看到一次正确的执行顺序可能是因为这次恰好没有并发也可能是因为你手动改了某处状态。最小复现把它往前推一步脱离业务代码只留必要输入。单测断言是最后一层它把“我看到”变成“它必须”以后改源码、换版本跑一遍就知道有没有被破坏。下面这段断言是我验证track次数时用的模板核心是数“副作用执行了几次”而不是数日志。import { describe, it, expect, vi } from vitest import { reactive, effect, stop } from vue/reactivity describe(effect 的依赖收集边界, () { it(只读取一个属性时修改其它属性不应触发重跑, () { const state reactive({ a: 1, b: 2 }) const spy vi.fn(() state.a) // 只访问 a const runner effect(spy) expect(spy).toHaveBeenCalledTimes(1) // 首次执行 state.b // 访问 b 不等于收集了 b expect(spy).toHaveBeenCalledTimes(1) state.a // 访问过 a才会被触发 expect(spy).toHaveBeenCalledTimes(2) stop(runner) // 手工停止验证依赖已被清理 state.a expect(spy).toHaveBeenCalledTimes(2) }) })这段断言的关键在最后三行stop之后spy的调用次数不再增长说明依赖集合里的这个 effect 被移除了。如果你手上的版本在stop之后仍然触发那大概率是清理逻辑的分支和你读的那段源码不是同一版本——这就是单测的价值它逼你去确认版本而不是凭记忆下结论。还有一个小技巧验证分支覆盖时用state.b这类“读了但没改对”的操作比直接改a更能暴露问题。trigger在找不到对应依赖集合时应当直接返回如果它误触发了整个 target 的所有依赖第一次state.b就会让spy多跑一次。很多人读完源码觉得“这里肯定有判断”但从来没验证过判断真的生效。最后说一个我自己踩过的坑。我早期读源码有个坏习惯看到优化分支就跳过只读主流程觉得“优化不影响理解”。结果在一次排查里我笃定某个属性变更会触发重渲染实际却没触发查了半天才发现是编译期打了patchFlag运行时只比对了文本属性压根没进 diff 流程。从那以后我每次对某个结论有把握的时候都强制走一遍“类型检查 单测断言”这两步把“我觉得”换成“它必须”。源码学习资源真正的价值不在于它写得多全而在于它给了你一套可以反复验证的结构你照着跑通的每一条断言都是以后排查线上问题的后悔药。希望帮到你。本文还有配套的精品资源点击获取