企业官网建设流程全解析

• 开发工具
• IDE
• 语言服务

本篇技术文章以本仓库changelogs/CHANGELOG-v2.md为骨架，系统梳理 Vue Language Tools（基于 Volar.js 的高性能 Vue 语言工具集）2.x 系列从 2.0.0 到 2.2.10 的完整演进历程，并结合packages/language-core、extensions/vscode、packages/tsc等子包的源码实现，深入讲解 Hybrid Mode 架构、模板内$attrs/$slots/$refs/$el类型推断、strictTemplates细粒度配置、@vue-generic、defineModel/defineSlots支持以及vueCompilerOptions的解析原理。读者读完后，将能理解 Vue 语言工具底层代码生成与类型推断的工作机制，并能熟练配置tsconfig.json中的vueCompilerOptions与 VS Code 扩展设置，掌握从 2.0 到 2.2 的关键能力变化。

一、2.x 版本全景与发布节奏

Vue Language Tools（仓库内即 language-tools，核心包为@vue/language-core）的 2.x 系列横跨 2024 年 3 月至 2025 年 4 月，官方版（official）与内测版（insiders）并行发布。其版本节奏与里程碑如下：

2.x 系列整体围绕三条主线展开：编辑器架构从 Takeover Mode 迁移到 Hybrid Mode、模板类型推断能力大幅增强（逼近 Vue 3.4/3.5 的运行时语义）、底层代码生成与语言服务架构持续重构（基于 Generator 的 codegen、Plugin API 2.1、vueCompilerOptions解析逻辑重写）。

二、架构重构：从 Takeover Mode 到 Hybrid Mode

2.1 2.0.0 的里程碑式变革

2.0.0 是 2.x 系列的起点，也是架构分水岭。根据 CHANGELOG-v2.md 中 2.0.0 小节，本次大版本做了如下核心调整：

• Takeover Mode 被废弃：扩展默认即可获得与 Takeover Mode 相同的性能；
• TypeScript 语言支持从 Vue 语言服务器迁移到 TypeScript 插件（issue #3788），即由@vue/typescript-plugin承担模板内 TS 的补全、跳转、重命名等能力；
• 集成全部 TypeScript 编辑器特性，包括语义 token（#3915）、auto-import 补丁（#3917）、.value自动插入（#3914）等；
• 迁移到基于 TypeScript LanguageService 的命名管道服务器（#3908、#3916），并取消typescript.tsdk重复注册错误提示；
• 扩展更名：原 "Volar Language Features (Volar)" 更名为"Vue - Official"，原 "TypeScript Vue Plugin" 扩展被废弃；
• Volar 升级到 2.0/2.1（#3736、#3906），支持 Volar Labs v2。

这一系列变更意味着 Vue 的 IntelliSense 不再依赖一个独立语言服务器去“接管”TS，而是作为 TypeScript 的插件直接挂载在 tsserver 中。后续版本中@vue/typescript-plugin包从typescript-plugin目录独立而出并更名为@vue/typescript-plugin（#3910），其源码位于 packages/typescript-plugin。

2.2 Hybrid Mode 的默认值反转

2.0.7 发布了一个重要行为变更（CHANGELOG 中以[!NOTE]醒目标注）：

Hybrid Mode is now disabled by default, you need to enablevue.server.hybridModein settings to enable it explicitly.

即 Hybrid Mode 默认关闭，用户需要在设置中显式开启vue.server.hybridMode。2.0.11 进一步为vue.server.hybridMode增加了typeScriptPluginOnly选项：当 Hybrid Mode 关闭时，Vue TypeScript Plugin 默认也被禁用。2.0.10 则引入"尽可能自动开启 Hybrid Mode"（#4206）以及自动检测的跳过配置（#5046），并对GitHub.copilot-chat（#5047）、ms-dynamics-smb.al（#4765）、p42ai.refactor、nrwl.angular-console、styled-components.vscode-styled-components、Divlo.vscode-styled-jsx-languageserver、svelte.svelte-vscode、vue vine、kimuson.ts-type-expand、miaonster.vscode-tsx-arrow-definition、runem.lit-plugin、mxsdev.typescript-explorer、bierner.lit-html、denoland.vscode-deno、jenkey2011.string-highlight等扩展加入了 Hybrid Mode 兼容白名单，以降低与其他 TS 插件的冲突（例如 Volar.js #216 的兼容性改进）。

2.3 扩展的编辑器设置项演进

伴随架构重构，VS Code 扩展（extensions/vscode/package.json）的设置项也经历了多次调整：

• 2.0.0 移除了volar.format.initialIndent，替换为三个独立开关：vue.format.template.initialIndent、vue.format.script.initialIndent、vue.format.style.initialIndent（对应 extensions/vscode/package.json 中的vue.format.*配置）；
• 2.0.6 将vue.inlayHints.vbindShorthand重命名为vue.inlayHints.vBindShorthand（#3995）；
• 2.0.11 新增vue.format.wrapAttributes（#4212）与vue.codeActions.askNewComponentName（#4217）；
• 2.1.0-insiders.3 新增vue.editor.reactionsVisualization设置（反应可视化，PR #8）；
• 2.1.0-insiders.1 引入模板插值装饰器，可通过vue.editor.templateInterpolationDecorators关闭；
• 2.0.28-insiders 引入 Focus Mode（聚焦模式，淡化顶层 SFC 标签），对应设置vue.editor.focusMode。

上述设置在 extensions/vscode/package.json 中均有定义。例如vue.editor.focusMode默认false、vue.editor.reactivityVisualization默认true、vue.editor.templateInterpolationDecorators默认true。Focus Mode 的实现位于 extensions/vscode/src/focusMode.ts，它监听vue.editor.focusMode配置变化（watch(() => config.editor.focusMode, ...)），当开启且光标位于 SFC 顶层标签块内时，对非活动块做淡化处理。2.1.8-insiders 还增强了反应可视化对更多使用场景的识别。

三、language-core 代码生成引擎的演进

@vue/language-core（packages/language-core）负责将 Vue SFC 解析并转换为 TypeScript 可理解的虚拟代码结构，是@vue/language-server与vue-tsc的底层依赖。2.x 期间该引擎经历了多轮重构。

3.1 基于 Generator 的 codegen 重写

• 2.0.0 将代码生成器重构为基于 Generator（#3778），并把全局类型收敛为单个虚拟文件生成（#3803）；
• 2.1.0 提取 SFC 根标签为独立虚拟代码、移除__hint技巧、减少组件标签生成的虚拟代码（#4714）、不再用函数包裹模板虚拟代码（#4731），并将共享全局类型以真实文件写入 FS（#4736）；
• 2.2.4 拆分__VLS_templateResult（#4781）、将模板虚拟代码包裹进函数（#4784）、把templateRef移入composables（#4791）；
• 2.2.2 重写vueCompilerOptions解析逻辑、减少模板 return 的 codegen 体积；
• 2.1.8 拆分__VLS_templateResult，避免为插值边缘生成零长度映射。

当前 codegen 代码分布在 packages/language-core/lib/codegen 下，按 script/style/template 分类，模板部分细分出elementProps.ts、elementEvents.ts、elementDirectives.ts、vFor.ts、vIf.ts、vSlot.ts、slotOutlet.ts、interpolation.ts等模块。

3.2 Plugin API 2.1 与内置插件体系

2.0.28 引入Plugin API 2.1：新增插件钩子getLanguageId、isValidFile、parseSFC2（#4585），并改善向后兼容性（#4585）与嵌套插件（#4581）。2.0.18 还增加了compileSFCScript插件钩子（#3200）。这些钩子的类型定义在 packages/language-core/lib/types.ts 的VueLanguagePluginReturn接口中，而内置插件则位于 packages/language-core/lib/plugins，包括：

• 文件解析类：file-vue（.vue，受extensions控制）、file-md（Markdown，受vitePressExtensions控制）、file-html（HTML，受petiteVueExtensions控制）；
• 虚拟代码生成类：vue-tsx、vue-template-html、vue-template-inline-ts、vue-template-inline-css、vue-style-css、vue-script-js；
• 内嵌代码提取类：vue-sfc-template、vue-sfc-styles、vue-sfc-scripts、vue-sfc-customblocks。

2.2.2 还将 inline CSS 的 codegen 拆分为独立插件、把全局类型 codegen 移入独立脚本、并在 push 代码前解析虚拟代码特性。2.1.0 起component-meta移除了createComponentMetaCheckerByJsonConfig、createComponentMetaChecker两个旧 API。

3.3vueCompilerOptions解析逻辑与strictTemplates细分化

vueCompilerOptions是tsconfig.json中配置 Vue 编译行为的核心入口。2.2.2 重写了其解析逻辑，当前实现在 packages/language-core/lib/compilerOptions.ts：createParsedCommandLine/createParsedCommandLineByJson通过 TS 的readJsonConfigFile+parseJsonSourceFileConfigFileContent解析 tsconfig，并逐层收集被extends的配置中的vueCompilerOptions段；CompilerOptionsResolver.addConfig对每个配置做合并。

其中最值得关注的是strictTemplates的展开机制（#5138）。在 compilerOptions.ts 中：

case 'strictTemplates': const strict = !!options.strictTemplates; this.options.strictVModel ??= strict; this.options.checkUnknownProps ??= strict; this.options.checkUnknownEvents ??= strict; this.options.checkUnknownDirectives ??= strict; this.options.checkUnknownComponents ??= strict; break;

即strictTemplates: true只是一个便捷开关，会被展开为五个独立选项。从 2.2.2 起，用户可以不再依赖strictTemplates整体开关，而是通过 packages/language-core/README.md 与 packages/language-core/lib/types.ts 中VueCompilerOptions接口所定义的细粒度选项逐一控制：

这些选项在代码生成阶段的落点可以在模板 codegen 中看到：checkUnknownDirectives用于对非内置指令生成验证代码（elementDirectives.ts 中的verification: options.vueCompilerOptions.checkUnknownDirectives && !isBuiltInDirective(prop.name)），checkUnknownEvents则控制事件类型是否退化为Record<string, unknown>（elementEvents.ts）。2.0.18 还实现了strictTemplates开启时报告未知事件（#3718）。

除类型检查外，vueCompilerOptions还包含文件处理与高级选项。默认值由getDefaultCompilerOptions提供（compilerOptions.ts），常用项如下：

插件继承方面，plugins声明的配置会替换继承列表、[]表示清空，未声明则保留继承（测试见 packages/language-core/tests/compilerOptions.spec.ts）。

2.2.0 还支持在 SFC 根注释中配置vueCompilerOptions（#4987），例如通过<template>顶部注释覆盖局部编译选项，实现了单文件级的配置能力。

四、模板类型推断的里程碑：从$attrs到@vue-generic

2.x 中后期，language-core 的模板类型推断能力大幅增强，逐步覆盖 Vue 运行时的高级语义。

4.1 组合式 API 全局变量的类型支持

• $attrs：2.2.0 提供$attrs类型支持（#5076），2.2.2 支持useAttrs（#5106）以及$attrs/$slots/$refs/$el在模板中的导航支持（#5056），并将本地$attrs与__VLS_ctx.$attrs求交（#5113）；
• $slots/useSlots：2.2.0 提供类型支持（#5055），并将__VLS_slots与__VLS_ctx.$slots求交（#5083）；
• $refs/useTemplateRef：2.1.0 自动推断$refs与useTemplateRef类型（#4644），2.1.6 将模板 ref 包装unref（#4777）、推断原生模板 ref 为内置元素接口（#4786）；
• $el：2.1.8 自动推断$el类型（#4805）。

2.2.4 为此引入了一组推断控制选项（#5135）：inferComponentDollarEl、inferComponentDollarRefs、inferTemplateDollarAttrs、inferTemplateDollarEl、inferTemplateDollarRefs、inferTemplateDollarSlots，默认均为false，见 types.ts。

4.2v-model与 model 语义

• 2.2.0 支持v-modelmodifiers 类型（#5061）、使 model modifiers 可选（#4978）；
• 2.2.4 修复带默认值的 model 不发出undefined（#5198）；
• 2.2.6 从defineModel前置注释推断 prop JSDoc（#5211）、为defineModel生成驼峰 prop 名（#5213）、校验v-model变量与 model 类型（#5214）、正确映射驼峰 prop 名（#5207）；
• 2.2.10 为 model 事件生成条件守卫（#5225）。

2.0.x 阶段还完成了defineModel的 emits 代码生成（2.0.0，#3895）、按需生成defineModelemits 类型（2.0.7，#4052）、从 options 类型推断 defineModel 类型（2.0.28，#4545）、为泛型组件支持 defineModel（2.0.17，#4345）、v-model无参数时的类型检查（2.0.28，#4598）等。

4.3 指令、事件与透传属性的类型化

• typed directives：2.1.6 在模板中支持类型化指令（#4807），2.1.8 支持类型化的指令参数与 modifiers（#4813）；
• typed fallthrough attributes：2.1.0 支持类型化透传属性（#4103），并伴随fallthroughAttributes与checkRequiredFallthroughAttributes两个编译选项；
• 事件：2.0.18 修复连字符事件名的处理、允许同名事件多次绑定（#4369）；2.1.0 修正vue:事件类型与补全（#4969）；2.2.2 为可选 model emits 的首参补undefined（#5171）。

4.4 泛型：@vue-generic与泛型组件

2.2.0 正式支持@vue-generic（#4971），允许在<script setup>顶层注释中声明组件泛型。其解析实现在 packages/language-core/lib/plugins/vue-template-inline-ts.ts，通过正则^<!--\s*@vue-generic\s*\{(?<content>[\s\S]*)\}\s*-->$提取泛型内容。2.2.4 还修复了@vue-generic正则匹配以改善 offset 计算（#5193）。

泛型组件的类型处理在 2.0.x 已持续打磨：2.0.28 修复泛型组件虚拟代码与 TS 5.5 的兼容（#4577）、2.1.8 避免解构 props 导致泛型类型丢失（#4821）、修复defineModel/defineEmits在泛型中的类型推断（#4823）、将泛型组件 props 与 attrs 求交（#4886）、2.1.6 修复非泛型模板 ref 的expose必填问题（#4795）。

4.5 其他模板语义修复

• v-for：2.2.2 对齐 core 的v-for类型（#5084）、改进v-for的类型声明（refactor）；2.1.8 修复v-for搭配v-once（#4830）、v-for中的Reactive包裹（#4902）、通过v-for推断原生元素模板 ref 类型（#4933）；
• defineSlots解构（2.0.15 #4312、2.0.16 #4326、#4327）；
• defineProps解构的 inlay hints（2.1.0，#4634），component-meta收集解构 props 默认值（2.2.2，#5101）；
• v-bind简写（2.0.5，#3990）与简写 inlay hints（2.0.5）；
• 模板 ref 导航（2.1.4，#4726）、:class类名文档链接（2.1.0，#4642）；
• 样式模块__VLS_StyleModules生成时机（2.1.6，#4790）、CSS Modules API 类型支持（2.1.0，#4674）、useCssModule的as断言注入位置（2.1.10，#4952）；
• @vue-ignore/@vue-expect-error可靠性改进（2.0.11，#4203）及文档（2.2.4，#5176）。

五、language-service 与编辑器体验增强

5.1 补全、hover 与 inlay hints

• 补全：2.1.0 改进指令补全（#4640）、补全排序与过滤（#4671）；2.1.6 输入组件 props 时显示 JSDoc（#4796）；2.2.2 支持全局指令补全（#4989）、补全中显示 props 的废弃信息（#5134）；2.1.10 自动插入const props =（#4942）；2.2.0 处理特殊结束标签补全的文本编辑（#5016）；
• hover：2.1.6 增加 JSDoc 显示；
• inlay hints：2.2.0 为 inlay hints 配置增加示例（#5068）；
• 格式化：2.1.0 移除extraLiners选项（#3943）。

5.2 代码映射与虚拟代码重构

• 2.2.2 起 language-service 直接从 codegen 读取 AST，而非反复解析（#5086）；
• 2.1.0 迁移测试到@volar/test-utils（#4719）；
• 2.0.10 将每个插值生成为独立虚拟代码（#4165）；
• 2.2.4 将 SFC 编译器错误映射到模板内层内容之外（#5045）。

5.3 组件拖拽导入与模块转换

2.0.0 支持Component Drag and Drop Import（#3692）：在模板中拖拽组件即可自动生成 import。2.0.10 增强为拖拽导入遵循 tsconfig 路径别名（#4184）、支持多光标自动插入（#4140）。相关代码生成逻辑位于 extensions/vscode/src/registerModuleTransform.ts。

六、CLI 与生态包：tsc、component-meta、pug 插件

6.1vue-tsc的重写

2.0.0 将vue-tsc重写为基于第一方 TS API，不再依赖 TypeScript 模块加载方式（#3795），并废弃 hooks API（#3793）。2.0.28 起错误以抛错而非console.log打印；2.0.7 重引入全局类型移除检查（#4245）；2.0.10 为 composite 项目移除虚假全局类型占位（#4196）；2.2.0 指向 shimmed tsc 入口以支持 TS 5.7（#5020）。vue-tsc的类型检查测试用例集中在 packages/tsc/tests 与 test-workspace/tsc。

6.2 component-meta

2.x 期间component-meta转为 TS 源码（2.0.15），并重构为直接读取 codegen 的scriptSetupRanges（2.2.2），或从sfc.script读取 AST（2.2.2），避免重复创建子 AST。功能上新增 defineModel modifiers 类型解析（2.0.10，#4175）、事件 JSDoc 标签支持（2.0.17）、resolvedefineModeloptions 收集默认值（2.2.6，#5209）。

6.3 language-plugin-pug 与额外扩展支持

• Pug 插件（packages/language-plugin-pug）：2.1.6 支持初始缩进（#4774）；2.1.0 缓存 proxyed 对象（#4626）、正确计算 pug class 偏移（#4652）；2.2.2 忽略class重复属性错误（#5100）；2.0.7 修复语义 token 映射失败（#4070）；
• 额外扩展：2.0.15 重新设计 VitePress、PetiteVue 等额外扩展支持（#4321），修复 Hybrid Mode 下自定义文件扩展不生效（#4251）；2.1.4 与 2.1.2 系列修复了additionalExtensions在 inferred project 下不生效的问题（#4251、#3959）。

6.4 全局类型文件的管理

2.x 对全局类型文件的生成与引用做了多轮修正：2.0.0 改为单虚拟文件生成（#3803）；2.1.4 生成到node_modules/.vue-global-types（#4752）、文件名应用 snake case（#4749）、禁用 lib check（#4767）；2.1.2 写入 dist 以正确导出（#4740）；2.1.0 写真实文件到 FS 共享全局类型（#4736）；2.1.8 改为相对路径引用（#4966）后又改为绝对路径（#4924）；2.2.10 防止在声明文件中生成全局类型（#5239）。

七、Volar 底层升级与配套改进

2.x 全程跟随 Volar.js 版本升级，CHANGELOG 记录了每次升级的关键收益，例如：

• 2.0.0：升级 Volar 2.0/2.1；
• 2.0.4/2.0.5：@volar/typescript修复 2.0.5 自动补全性能回退（#4024）；
• 2.0.14：修复 Hybrid Mode 下的参数提示（#3948）、大型 JS 文件导致 TS server 崩溃（#4278）、重命名/查找定义随机报错（#4257/#4281/#4282）等；
• 2.0.20：LSP 服务器性能提升、初始化请求返回精确 server capabilities、auto insertion 请求提前退出；
• 2.1.0：确保未打开文件同步到项目（#4711/#4632）；
• 2.2.0：升级 Volar 2.2，修复未打开文件未注册项目（#4711）、tsc shim（#252）等；
• 2.2.0 末：Volar v2.4.8→v2.4.11（2.2.0 到 2.2.10 期间）持续修复超大文件 relatedInformation 崩溃、交互式重构（#244）、语言插件就绪后强制更新快照等。

八、质量保障与工程化

CHANGELOG 的 "Other Changes"/"Tests" 部分展示了 2.x 的工程化投入：

• 测试：2.2.4 启用declaration以跟踪更多错误；2.1.0 用单一 tsconfig 测试全部 typecheck 用例（#4723）、为 TS-next 增加测试（#4724）、添加 scoped 类重命名用例（#4727）；2.1.6 增加模板ref()重命名用例（#4794）；2.0.28 添加全局组件 prop 校验测试（#4542）；2.0.11 增加 #4203 测试（#4207）；
• CI：2.0.0 起pkg.pr.new集成（2.1.0）；2.2.4 每次提交上传扩展产物；2.2.6 自动关闭标记为can't reproduce的 issue；
• 代码规范：引入tsllinter 与自动修复工作流（2.0.7，#4100），仓库根 package.json 的lint脚本基于 tsslint 运行；启用 dprint 格式化（根 dprint.json）；
• 依赖清理：2.1.8 移除副作用（#4871）、移除importsNotUsedAsValues（#4897）；2.1.0 修复依赖存在漏洞的vue-template-compiler版本（#4613）。

九、2.x 收官与经验总结

2.2.10（2025-04-22）作为 2.x 的收官版本，重点修复了 model 事件条件守卫（#5225）、声明文件中的全局类型生成（#5239）、泛型 slot props 的过早推断（#5247）以及 typescript-plugin 中对同名原生标签的高亮问题（#5253）。随后仓库整体进入 3.x 时代（当前扩展版本号已到 3.3.13，见 extensions/vscode/package.json）。

回顾 2.x 的演进，可以提炼出几条对使用者与二次开发者都适用的经验：

1. strictTemplates已可细粒度控制：若只想严格检查未知指令而放行未知事件，直接设置checkUnknownDirectives: true即可，无需再打开整体开关；
2. Hybrid Mode 是默认关闭的：需要在设置中显式开启vue.server.hybridMode，并留意兼容白名单内的扩展冲突；
3. @vue-generic提供了声明泛型组件的官方通道，配合defineModel/defineSlots解构与类型化透传属性，模板内的类型安全已接近运行时语义；
4. 插件体系（Plugin API 2.1）是扩展 language-core 能力的入口，vueCompilerOptions.plugins支持加载@vue/language-plugin-pug等外部插件，且继承规则为"声明即替换"。

若需深入了解本文涉及的实现细节，可继续阅读：vueCompilerOptions解析与默认值见 packages/language-core/lib/compilerOptions.ts，选项类型定义见 packages/language-core/lib/types.ts，配置文档见 packages/language-core/README.md，模板指令与事件的类型化实现见 packages/language-core/lib/codegen/template/elementDirectives.ts 与 elementEvents.ts，编辑器设置见 extensions/vscode/package.json，而全部历史条目可回溯 changelogs/CHANGELOG-v2.md 本身。

• 开发工具
• IDE
• 语言服务