企业官网建设流程全解析

void 项目 HTML 语言特性扩展（html-language-features）开发调试与贡献指南

【免费下载链接】void开源AI代码编辑器，Cursor的替代方案。项目地址: https://gitcode.com/GitHub_Trending/void2/void

导读

本文面向希望在 void 开源 AI 代码编辑器中参与 HTML 语言特性（html-language-features）扩展开发的贡献者，系统讲解如何从零搭建开发环境、编译客户端与服务端、通过 VS Code 扩展宿主调试完整的「客户端 + 语言服务器」链路，以及如何利用npm link联动vscode-html-languageservice开发版本来交互式调试 HTML 语言服务。读完本文，你将掌握该扩展的调试配置、进程附加方式、日志观测方法，并能把语言服务的「智能逻辑」与「外壳封装」两条开发路径区分开，直接上手贡献。

本指南的主体内容取自仓库内的 extensions/html-language-features/CONTRIBUTING.md，并结合该扩展的客户端、服务器源码与调试配置进行深度展开。

一、扩展架构速览：先理解「外壳」与「智能」的分工

在动手搭建环境之前，有必要先厘清 html-language-features 扩展的内部结构。该扩展位于 extensions/html-language-features/，本质上是「VS Code 客户端 + Language Server 服务器」的经典 LSP 架构：

• 客户端（client/）：运行在编辑器主进程中的扩展部分，负责监听打开 HTML/Handlebars 文件等激活事件、启动语言服务器进程并与之通过 LSP 协议通信。入口为 client/src/node/htmlClientMain.ts（Node 环境）与 client/src/browser/htmlClientMain.ts（浏览器环境）。
• 语言服务器（server/）：独立进程，接收客户端的请求并返回补全、悬停、格式化、诊断等结果。入口为 server/src/node/htmlServerMain.ts，其核心逻辑在 server/src/htmlServer.ts 中通过startServer(connection, runtime)统一装配。
• 语言智能（vscode-html-languageservice）：真正懂得 HTML 语法、标签、属性、嵌入语言的第三方库，由服务器包装后暴露为 LSP 能力。这一点在 CONTRIBUTING.md 中被反复强调：修复 HTML 本身的问题应去改vscode-html-languageservice，而不是改这个扩展。

从 server/package.json 可以看到服务器的运行时依赖：

客户端一侧则由 client/package.json（即扩展根 package.json）中的vscode-languageclient提供 LSP 客户端能力。

理解了这个分层，后面的调试步骤就有清晰的靶向：想调「通信与外壳」断点打在 client/ 与 server/ 源码里；想调「语言智能」断点打在通过npm link链接进来的vscode-html-languageservice源码里。

二、环境搭建：三步完成依赖安装

CONTRIBUTING.md 给出的 Setup 流程如下：

1. 克隆 void 仓库（本仓库根目录即 VS Code 主仓库形态）；
2. 在仓库根目录执行npm i，一次性安装全部依赖，包括：
   • extensions/html-language-features/的依赖（客户端侧）；
   • extensions/html-language-features/server/的依赖（服务器侧）；
   • gulp等 devDependencies（编译扩展使用）；
3. 以 extensions/html-language-features/ 作为工作区在 VS Code 中打开；
4. 在该目录下执行npm run compile（或npm run watch）构建客户端与服务器。

其中npm run compile与npm run watch的具体命令定义在 extensions/html-language-features/package.json 的scripts字段：

"compile": "npx gulp compile-extension:html-language-features-client compile-extension:html-language-features-server", "watch": "npx gulp watch-extension:html-language-features-client watch-extension:html-language-features-server"

即通过仓库根目录的 gulp 任务分别编译客户端与服务器，compile为一次性构建，watch则在文件变更时增量重建。编译产物分别输出到client/out与server/out（webpack 打包版输出到client/dist与server/dist，详见 extension.webpack.config.js 与 server/extension.webpack.config.js）。

服务器侧也提供了单独的构建脚本，见 server/package.json：

"compile": "npx gulp compile-extension:html-language-features-server", "watch": "npx gulp watch-extension:html-language-features-server"

验证服务器可独立运行

服务器进程本身是独立可运行的 Node 程序，其 server/src/node/htmlServerMain.ts 中创建了 LSP 连接（createConnection()），把console.log重定向到 LSP 通道，并注册了unhandledRejection处理器，然后调用startServer(connection, runtime)启动。这与你后续用Attach to Node Process附加调试的目标进程是同一个。

三、启动扩展宿主调试：Launch Extension 目标

依赖安装完成后，在 Debug View 中运行Launch Extension调试目标。该目标定义在 extensions/html-language-features/.vscode/launch.json：

{ "name": "Launch Extension", "type": "extensionHost", "request": "launch", "runtimeExecutable": "${execPath}", "args": [ "--extensionDevelopmentPath=${workspaceFolder}" ], "stopOnEntry": false, "sourceMaps": true, "outFiles": ["${workspaceFolder}/client/out/**/*.js"] }

该配置会启动一个加载了当前扩展的新 VS Code 实例（extension host），--extensionDevelopmentPath指向工作区（即 html-language-features 扩展目录）。整个调试过程的核心链路是：

1. 在新实例中打开一个.html文件，触发扩展激活——扩展在 extensions/html-language-features/package.json 中声明的激活事件为onLanguage:html与onLanguage:handlebars；
2. 客户端激活后，根据 client/src/node/htmlClientMain.ts 的逻辑，以TransportKind.ipc启动语言服务器进程，入口模块为./server/{dist|out}/node/htmlServerMain；
3. 语言服务器进程随之启动，开始提供补全、悬停、格式化等语言能力。

观测客户端与服务器的通信

为观察两者之间的 LSP 报文，在设置中添加：

"html.trace.server": "verbose"

该设置对应 extensions/html-language-features/package.json 中html.trace.server配置项，取值可为off、messages、verbose（默认off）。设为verbose后，可在输出面板的HTML Language Server通道中看到客户端与服务端之间完整往返的 JSON-RPC 消息（该通道由 client/src/htmlClient.ts 中的window.createOutputChannel(languageServerDescription)创建，languageServerDescription即HTML Language Server）。

客户端断点调试

在 extensions/html-language-features/client/src/ 下的源码中设置断点即可调试扩展客户端与语言服务器客户端的交互逻辑。例如：

• htmlClient.ts中的startClient负责创建语言客户端、同步html/css/javascript/js/ts配置节、注册语义令牌与格式化 provider；
• autoInsertion.ts负责自动补全引号与自动闭合标签；
• customData.ts负责加载自定义 HTML 数据（html.customData）；
• languageParticipants.ts负责识别哪些语言参与 HTML 语言特性（例如 HTML 内嵌的 JS/CSS 由哪些扩展提供支持）。

四、附加调试语言服务器进程：Attach 与端口断点

语言服务器是独立进程，因此需要额外的附加步骤。CONTRIBUTING.md 给出的方法是使用Attach to Node Process命令：

1. 在打开 html-language-features 的 VS Code 窗口中，运行命令面板中的Attach to Node Process；
2. 选择命令行中包含htmlServerMain的进程（将鼠标悬停在code-insiders/code进程上可查看完整命令行，以此确认目标）；
3. 在 extensions/html-language-features/server/src/ 下的源码中设置断点，即可命中服务器侧的请求处理逻辑。

为什么服务器进程带--inspect

客户端在启动服务器时，为调试场景注入了调试参数。见 client/src/node/htmlClientMain.ts：

const debugOptions = { execArgv: ['--nolazy', '--inspect=' + (8000 + Math.round(Math.random() * 999))] };

--inspect会在 8000~8999 之间随机分配一个调试端口，因此使用「按进程附加」的方式比固定端口更可靠——这也正是 CONTRIBUTING.md 推荐Attach to Node Process而非固定端口附加的原因。

方案二：通过 launch.json 固定端口附加

仓库同时提供了固定端口的附加配置。在 extensions/html-language-features/.vscode/launch.json 中定义了Attach Language Server配置：

{ "name": "Attach Language Server", "type": "node", "request": "attach", "port": 6045, "protocol": "inspector", "sourceMaps": true, "outFiles": ["${workspaceFolder}/server/out/**/*.js"], "restart": true }

该配置固定附加到 6045 端口。与之对应，extensions/html-language-features/.vscode/launch.json 还提供了 compound 配置Debug Extension and Language Server，可一键同时启动「Launch Extension」与「Attach Language Server」，实现客户端与服务器双端联动调试。注意：若要使用固定端口附加，需要自行保证服务器进程监听的是该端口（随机端口逻辑位于客户端源码中，可结合调试需要调整）。

提示：服务器端独立调试配置还见于 server/.vscode/launch.json，其中Attach同样使用 6045 端口、Unit Tests通过 mocha 运行服务器单元测试，测试入口逻辑见 server/test/index.js。

服务器源码的断点落点

server/src/htmlServer.ts 中的startServer是服务器全部请求处理的枢纽，适合设置断点的位置包括：

• connection.onInitialize：初始化时协商能力（补全、悬停、格式化、语义令牌等），并依据客户端能力决定是否开启 snippet 支持、动态格式化注册、诊断推送/拉取模式；
• connection.onCompletion/onCompletionResolve：补全建议与补全项解析；
• connection.onHover：悬停信息；
• connection.onDocumentFormatting/onDocumentRangeFormatting：格式化，内部通过format(languageModes, ...)调用modes/formatting.ts；
• connection.onFoldingRanges/onSelectionRanges/onRenameRequest：折叠、选区、重命名；
• CustomDataChangedNotification处理：自定义数据变更后刷新 language modes。

五、重载扩展：Reload Window

每次修改客户端或服务器源码并重新编译后，需要在新实例中执行Reload Window命令来重新加载扩展，使改动生效。这是调试循环中反复使用的操作：改代码 →npm run watch自动重编译 → Reload Window → 复现/验证。

六、开发 vscode-html-languageservice：npm link 联动开发版

CONTRIBUTING.md 强调：HTML 语言智能本体在独立的microsoft/vscode-html-languageservice仓库中，本扩展只是把它包装成 Language Server。因此：

• 要修复 HTML 语言特性本身的 bug 或做功能增强，应修改vscode-html-languageservice；
• 在等待上游发布新版本期间，可以在本扩展内通过npm link挂载开发版本来交互式调试。

Linking 步骤（在 html-language-features/server/ 中）

1. 克隆vscode-html-languageservice仓库；
2. 在其根目录执行npm i安装依赖；
3. 在其根目录执行npm link——这会编译并全局链接该包；
4. 在extensions/html-language-features/server/目录执行npm link vscode-html-languageservice，将全局链接的包挂载到服务器的node_modules。

测试开发版语言服务

1. 同时打开vscode-html-languageservice与本扩展两个窗口（或用多根工作区放在同一窗口）；
2. 在extensions/html-language-features/server/执行npm run watch，用链接版本的vscode-html-languageservice重新编译本扩展；
3. 在vscode-html-languageservice中修改代码；
4. 运行Launch Extension调试目标，新实例即会使用你的开发版语言服务，可交互式验证补全、悬停、格式化等语言特性是否如预期工作。

由于服务器依赖中声明的vscode-html-languageservice版本为^5.3.3（见 server/package.json），npm link实际上是在本地node_modules中用符号链接覆盖了 npm 安装的版本，从而让服务器加载你的本地开发代码。注意npm link属于本地开发工具链操作，如需恢复官方版本，在server/中执行npm install vscode-html-languageservice即可（对应install-service-local/install-service-next脚本的用途）。

七、服务器端单元测试与回归验证

贡献修改后应运行测试验证。服务器提供了 mocha 测试体系：

• 测试入口：server/test/index.js，通过 glob 收集out/test/**/*.test.js并运行；
• 运行命令：在server/下执行npm test（即npm run compile && node ./test/index.js）；
• 测试用例位于 server/src/test/，覆盖补全（completions.test.ts）、格式化（formatting.test.ts）、折叠（folding.test.ts）、嵌入语言（embedded.test.ts）、语义令牌（semanticTokens.test.ts）、重命名（rename.test.ts）、选区范围（selectionRanges.test.ts）、文档上下文（documentContext.test.ts）、分词（words.test.ts）等；格式化测试的期望输出位于 server/src/test/fixtures/expected/。

也可以在 Debug View 中运行Launch Tests目标（见 extensions/html-language-features/.vscode/launch.json），在带断点的交互环境下执行客户端侧测试。

八、常见问题与调试技巧小结

此外，涉及客户端/服务器交互层面的功能（如自动插入、语义令牌、自定义数据），可结合 client/src/ 与 server/src/ 两端的实现对照调试；涉及 HTML 语法语义本身的问题，则应把工作重心放在vscode-html-languageservice的开发版上。

结语

html-language-features 扩展的贡献流程可以概括为三条主线：搭建环境（npm i+npm run compile/watch）→ 双端调试（Launch Extension + Attach to Node Process）→ 联动语言服务（npm link vscode-html-languageservice）。理解「外壳（扩展/服务器）与智能（语言服务库）」的分层边界，是高效贡献的关键。本指南覆盖了 CONTRIBUTING.md 的全部步骤，并结合 client/、server/ 源码与 .vscode/launch.json 调试配置做了扩展，可作为你在 void 项目中参与 HTML 语言特性开发的完整操作手册。

【免费下载链接】void开源AI代码编辑器，Cursor的替代方案。项目地址: https://gitcode.com/GitHub_Trending/void2/void