vscode-web-visual-editor 构建与发布完整指南：esbuild 打包、jsdom 补丁与本地调试

vscode-web-visual-editor 构建与发布完整指南esbuild 打包、jsdom 补丁与本地调试【免费下载链接】vscode-web-visual-editorEdit HTML files visually.项目地址: https://gitcode.com/gh_mirrors/vs/vscode-web-visual-editorvscode-web-visual-editorWeb Visual Editor是一款让你实时可视化编辑 HTML 文件的 VS Code 扩展。本文带你完整走一遍它的构建与发布流程用esbuild把扩展打包成单文件、为什么要给jsdom打补丁、以及如何用 F5 快速完成本地调试新手也能从零到发布。1️⃣ 项目速览它靠什么工作打开任意.html文件点击标题栏的Visual Editor图标即可进入可视化预览️可视化编辑在预览中选中、移动、删除元素双向同步选中代码会高亮预览中的元素反之亦然✂️所见即所得复制/剪切/粘贴操作会直接写回源文件。扩展的核心依赖只有两个见package.json的 dependencies依赖作用jsdom在 Node 端解析 HTML建立DOM 元素 ↔ 源码位置的映射heHTML 实体转义与解码⚠️ 环境要求Node.js ≥ 25、VS Code ≥ 1.99package.json的engines字段。2️⃣ 安装依赖与第一次构建npm install npm run compilecompile实际是三步组合类型检查tsc --noEmit→ESLint 检查→esbuild 打包最终输出单文件dist/extension.js即package.json中声明的main入口。常用 npm 脚本一览脚本用途npm run compile一次性构建开发用npm run watch并行监听 esbuild tsc开发常驻npm run package生产构建压缩 无 sourcemapnpm run pretest测试前自动编译 lint3️⃣ esbuild 打包要点esbuild.js 里只有 3 个关键配置esbuild.js全文不过几十行核心就 3 处CJS Node 平台format: cjs且platform: node因为扩展运行在 VS Code 的 Node 宿主里排除 vscode 模块external: [vscode]这个 API 由宿主运行时提供绝不能打进包内生产开关加--production时开启 minify 并去掉 sourcemap开发模式则保留 sourcemap 方便断点调试。文件里还有两个插件各司其职esbuildProblemMatcherPlugin把构建错误打印成 VS Code 问题匹配器能识别的格式watch 模式下错误直接出现在问题面板jsdomPatch下一节的主角。另外传入--watch时走ctx.watch()常驻进程保存文件即自动增量重打包。4️⃣ 为什么必须给 jsdom 打补丁扩展在 Node 端用 jsdom 解析文档src/visualEditor.ts中new JSDOM(code, { includeNodeLocations: true })。includeNodeLocations让每个 DOM 节点都能对应回源码行号这正是预览选元素 ↔ 代码选位置同步的核心。但打包 jsdom 时XMLHttpRequest-impl.js里有一行require.resolve(./xhr-sync-worker.js)问题在于require.resolve的相对路径在打包后已经失效运行时会直接报错而扩展根本用不到 jsdom 的同步 XHR 能力。所以esbuild.js中的jsdomPatch插件用onLoad拦截该文件把这一行替换成const syncWorkerFile null;——一行补丁让整包可运行、零副作用。这是用 esbuild 打包带运行时require.resolve的依赖时的经典解法。5️⃣ 本地调试F5 一键打开扩展开发窗口项目已预置.vscode/launch.jsonRun Extension 配置按F5preLaunchTask会自动先执行compileVS Code 弹出一个新的扩展开发窗口新窗口把dist/extension.js当作当前扩展加载打开任意.html文件即可体验可视化编辑。两个让调试更顺手的细节监听任务.vscode/tasks.json把watch设为默认构建任务并行跑watch:esbuildwatch:tsc保存即热更新推荐扩展.vscode/extensions.json建议安装 ESLint 与 esbuild-problem-matchers装好后 esbuild 的报错会直接显示在问题面板可点击跳转。6️⃣ 打包与发布vsce 两步走package.json里的vscode:prepublish钩子会在发布前自动执行生产构建所以只需npx vscode/vsce package # 生成 .vsix 安装包 npx vscode/vsce publish # 发布到市场.vscode/tasks.json中也预置了vsce package/vsce publish两个任务可在终端面板直接调用。命令、图标、设置项如webVisualEditor.allowScript等package.json中的contributes声明会随包一起发布无需额外配置。7️⃣ 常见问题 FAQ现象排查建议watch 报错但问题面板无提示安装.vscode/extensions.json推荐的 esbuild-problem-matchers 扩展开发窗口里改动没生效确认在 watch 模式下保存了文件或重新 F5提示 Node 引擎版本不满足项目要求 Node ≥ 25先升级 Node 再npm install掌握以上流程后你就可以顺畅地开发、调试并持续发布这个 HTML 可视化编辑扩展了 【免费下载链接】vscode-web-visual-editorEdit HTML files visually.项目地址: https://gitcode.com/gh_mirrors/vs/vscode-web-visual-editor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考