Angular monorepo 中 VSCode Angular Language Service 扩展的本地开发指南依赖管理、VSIX 构建与调试【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular本篇技术指南面向希望在 Angular 主仓库angular/angular中为 VSCode Angular Language Serviceng-template扩展贡献代码的开发者完整讲解其 monorepo 组织方式、bazel-bin产物目录与依赖同步规则、通过pnpm --filterng-template run package构建.vsix安装包以及在 VSCode Extension Development Host 中一键编译、启动扩展开发实例并挂接语言服务器调试器的完整工作流。读完本文你将掌握从克隆仓库到「修改代码 → 自动编译 → 打开开发实例 → 附加调试器」的闭环开发方法。一、模块定位vscode-ng-language-service 在 Angular monorepo 中的角色Angular 主仓库是一个巨型 monorepo而vscode-ng-language-service是其中负责「编辑器体验」的独立子项目对应 VSCode 扩展ng-templatedisplayName 为 Angular Language Service。它并不直接包含 Angular 编译器的模板解析逻辑而是将 angular/language-service 与 TypeScript 编译器作为后端依赖通过语言服务器协议LSP为 VSCode 提供 Angular 模板的补全、诊断、跳转定义、文档符号Document Symbols与 Inlay Hints 等能力。其 LSP 服务器实现见 server/README.md 中描述的angular/language-server包。从目录结构看该模块由以下部分组成clientVSCode 扩展客户端负责激活扩展、管理语言客户端生命周期与命令注册server基于vscode-languageserver的 LSP 服务器实际承载语言能力common客户端与服务器共享的自定义 LSP 通知/请求定义如IsInAngularProject、GetTcbRequest等syntaxesTextMate 语法高亮定义inline-template、template-blocks、let-declaration 等integration集成测试与 e2e 测试工程。在开发该模块时需要理解一个核心前提这个 monorepo 的构建产物统一输出到bazel-bin目录。这意味着客户端与服务器源码通过 Bazel 编译后产物都落在bazel-bin下无论是打包.vsix还是调试加载都需要依赖这条产物链路。二、Monorepo 构建设置与依赖同步规则根据 DEVELOPER.md 的说明本项目是一个 monorepo所有构建输出都产生在bazel-bin目录中。例如客户端入口 package.json 中main字段指向../dist/bin/vscode-ng-language-service/client/src/extension.js即 Bazel 输出目录下的编译产物client.ts 在启动服务器时也同时探测生产包server与开发产物bazel-bin/server/src/server.js。2.1 根 package.json 必须覆盖全部生产依赖开发文档强调根目录 package.json 的dependencies必须包含客户端和服务器双方的全部生产依赖。这是因为 monorepo 采用单一锁文件pnpm-lock.yaml统一安装依赖任何一层缺漏都会导致构建或运行期解析失败。2.2 server 依赖需要在两处重复声明其中特别需要注意的是server 的依赖必须在根 package.json 中重复一份。因此每当为服务器新增一个生产依赖时需要同时把它添加到根 package.jsonserver/package.json。查看当前 server/package.json其生产依赖为angular/language-service: workspace:*与typescript: 6.0.3这两个包同样出现在根 package.json 与扩展 package.json 的dependencies中正是这一同步规则的落地体现。workspace:*表明使用工作区内源码版本的 language-service这也是扩展始终内置最新版 language-service 的原因。此外BUILD.bazel 中vsix_sandbox目标也手动列出了打包所需的传递依赖:node_modules/angular/language-service与:node_modules/typescript注释说明了这是为了避免vsce打包时额外执行一次npm install。三、构建扩展 .vsix 安装包3.1 执行打包命令如需构建扩展的.vsix安装包在仓库根目录执行pnpm --filterng-template run package该命令实际执行的是 package.json 中的package脚本package: bazel build //vscode-ng-language-service:development_package --configrelease即通过 Bazel 构建development_package目标使用 release 配置。3.2 产物位置构建完成后.vsix文件位于./dist/bin/vscode-ng-language-service/ng-template.vsix这个路径与 BUILD.bazel 中vsce规则vsix目标的产出ng-template.vsix一致也对应发布脚本 tools/release.mts 中extensionPath的取值。3.3 打包流水线拆解从 BUILD.bazel 可以还原完整的打包链路expand_template_rule生成package_expanded.json将workspace:*替换为实际版本号stamp 场景下用{{STABLE_PROJECT_VERSION}}否则用0.0.0并把main路径改写为./indexnpm_package组装vsix_sandbox汇集 CHANGELOG、README、icon、schema、client/server/syntaxes 编译产物及 language-service、typescript 两个 npm 包vsce_bin.vsce调用vsce package在vsix_sandbox目录内生成ng-template.vsix注意 args 中的--allow-package-env-file、--allow-package-all-secrets标志development_package将vsix与其 sandbox 一起打包供开发调试与 e2e 测试引用vsix_contents_golden_file生成并校验 vsix 内容清单对照文件为 goldens/vscode-extension/vsix_package_contents.txt。3.4 版本发布流程若需走完整发布流程版本号提升、changelog 生成、构建、打 tag、上传 release可运行扩展 package.json 中的release脚本node tools/release.mts。其实现位于 tools/release.mts流程包括校验工作区干净、读取当前版本并提示输入新版本默认建议 patch、创建vscode-release-version分支、生成 changelog、执行pnpm --filterng-template run package构建扩展、创建并推送vsix-version标签最后上传产物到 GitHub Release 并用vsce publish发布。注意该脚本依赖GITHUB_TOKEN环境变量且发布前会提示人工先在开发实例中验证产物。四、在 VSCode 中测试本地修改Extension Development Host对仓库中代码的任何修改都需要在一个开发版 VSCodeExtension Development Host扩展开发宿主窗口中实际验证。.vscode目录下的脚本已经配置好「自动编译代码 → 启动带 Angular 扩展的新 VSCode 实例」的完整链路。4.1 启动扩展开发客户端有两种方式启动在 VSCode 中直接按F5打开左侧 Run运行面板从任务列表中选择VSCE: Launch Dev Client。VSCE: Launch Dev Client对应 launch.json 中的extensionHost类型配置其关键参数为runtimeExecutable: ${execPath}—— 使用当前 VSCode 可执行文件作为宿主args: --extensionDevelopmentPath${workspaceFolder}/vscode-ng-language-service—— 以源码目录作为扩展开发路径加载preLaunchTask: VSCE: watch bundles—— 启动前先运行 watch 任务。preLaunchTask引用的VSCE: watch bundles定义在 tasks.json 中它执行pnpm --filterng-template run watch即ibazel build //vscode-ng-language-service/client/src //vscode-ng-language-service/server/src见 package.json以增量 watch 模式持续编译客户端与服务器源码并配置了beginsPattern/endsPattern两个背景任务匹配模式用于识别 ibazel 启动与构建完成的状态。4.2 附加调试器到语言服务器客户端启动后可以可选地将调试器附加到语言服务器进程打开左侧 Run运行面板从任务列表中选择VSCE: Attach to Server。该配置见 launch.json是node类型的 attach 请求监听6009端口并开启了 source maps 与sourceMapPathOverrides映射将?*/bin/*映射回工作区源码目录从而可以直接在server源码上打断点调试。为什么端口是 6009因为客户端在启动语言服务器时见 client.tsdebug 模式下会为 Node 进程追加--inspect-brk6009并设置NG_DEBUGtrue环境变量代码注释明确提示「如果修改调试端口请同步更新 .vscode/launch.json」。4.3 一步到位客户端 调试器作为快捷方式仓库还提供了一个组合任务可以一步完成「启动开发客户端并附加调试器」打开左侧 Run运行面板选择VSCE: Dev Client Attach to Server。该组合定义在 launch.json 的compounds中等价于依次执行VSCE: Launch Dev Client与VSCE: Attach to Server。4.4 其他可用的调试配置launch.json 中还提供了另外几组与调试测试相关的配置可配合使用VSCE: Launch Prod Client加载打包产物dist/bin/vscode-ng-language-service/development_packagepreLaunchTask为VSCE: package用于验证接近发布形态的扩展行为DEBUG: Attach to bazel testattach 到 9229 端口用于调试 Bazel 测试进程DEBUG: Run bazel test (Custom Target)交互式输入 Bazel target 后以--configdebug运行测试默认//packages/...DEBUG: Run bazel test (Custom Target) Attach两者组合一条命令跑测试并挂调试器。五、扩展激活与「trusted workspace」机制理解扩展如何启动有助于调试。扩展入口 extension.ts 的activate逻辑如下创建AngularLanguageClient并注册到context.subscriptions监听配置变更若涉及启动/会话相关配置见 config_change.ts则停止并重启语言服务器工作区未受信任时进入受限模式不启动语言服务器、不注册命令仅在用户授予信任onDidGrantWorkspaceTrust后才启动。这一点与扩展 package.json 中capabilities.untrustedWorkspaces声明「Angular 语言功能在非信任工作区中禁用」相互印证。客户端实际启动服务器的代码在 client.ts 的start()方法中通过vscode-languageclient以 IPC 传输方式启动服务器子进程debug 模式下使用--nolazy --inspect-brk6009参数与NG_DEBUGtrue环境变量生产模式下则直接加载扩展目录下的server模块。启动参数由constructArgs()根据 VSCode 配置动态拼装包括--logFile/--logVerbosity对应angular.log、--tsdk、--forceStrictTemplates、--suppressAngularDiagnosticCodes、--useClientSideFileWatcher等。六、测试本地修改单元测试、LSP 测试与 e2e除手工验证外DEVELOPER.md 之外的扩展 package.json 脚本还提供了完整的自动化测试入口test: bazel test --test_tag_filtersunit_test //vscode-ng-language-service/..., test:watch: ibazel test --test_tag_filtersunit_test //vscode-ng-language-service/..., test:lsp: bazel test --test_outputstreamed //vscode-ng-language-service/integration/lsp:test, test:e2e: bazel test --test_outputstreamed //vscode-ng-language-service/integration/e2e:test, test:inspect-client: bazel run --configdebug //vscode-ng-language-service/client/src/tests:test, test:inspect-common: bazel run --configdebug //vscode-ng-language-service/common/tests:test, test:inspect-server: bazel run --configdebug //vscode-ng-language-service/server/src/tests:test, test:inspect-syntaxes: bazel run --configdebug //vscode-ng-language-service/syntaxes/test:test,单元测试覆盖 client、common、server、syntaxes 四个子包的unit_test例如 server/src/tests 下的config_spec.ts、embedded_support_spec.ts、version_provider_spec.ts等LSP 集成测试integration/lsp/ivy_spec.ts 直接面向 LSP 协议层验证语言能力e2e 测试integration/e2e 中的completion_spec.ts、definition_spec.ts、hover_spec.ts在真实 VSCode 实例中验证补全、定义跳转与悬停提示。调试测试时test:inspect-*系列会以--configdebug运行配合前面提到的DEBUG: Attach to bazel test端口 9229即可在测试进程中打断点。七、开发工作流总结与常见注意点把以上内容串起来一次典型的本地开发迭代是修改 client 或 server 下的源码按F5或选择VSCE: Launch Dev Client.vscode/tasks.json中的VSCE: watch bundles会自动以 ibazel watch 模式编译增量产物在启动的开发宿主窗口中复现问题、验证修复需要单步调试服务器逻辑时选择VSCE: Dev Client Attach to Server一次性拉起客户端并挂接 6009 端口调试器需要验证产物形态时执行pnpm --filterng-template run package构建.vsix产物位于./dist/bin/vscode-ng-language-service/ng-template.vsix可用code --install-extension安装验证提交前运行pnpm --filterng-template run test、test:lsp、test:e2e保证各层测试通过。最后提醒几个容易踩坑的点依赖同步为 server 新增生产依赖时务必同步根 package.json 与 server/package.json否则 monorepo 锁文件或打包链路会出现解析失败调试端口一致语言服务器调试端口6009与 launch.json 中VSCE: Attach to Server的端口必须保持一致修改任一处需同步另一处产物目录一切 Bazel 输出都在bazel-bin对应dist/bin软链调试配置、main入口与打包规则都以此为前提不要在源码目录中寻找编译产物受信任工作区在非信任工作区中扩展只会提供语法高亮等受限能力语言服务器不会启动调试前请先确认工作区已授予信任。【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考