Summary

• 极快：使用 Bun 安装与运行脚本，开发/构建提速
• 自动：F5 前自动检查依赖（缺失时安装），保证一键运行
• 统一：@tomjs/vite-plugin-vscode 统一扩展与 Webview 构建
• 现代：React + Vite 开发体验，TypeScript 全面覆盖

目录

• 简介
• 快速开始
• 开发与调试
• 项目结构
• 架构与流程图
• 依赖检查脚本
• 常见问题排查
• 设计建议
• 许可证

简介

本模板旨在让你用最少的配置启动 VS Code 插件开发：扩展逻辑与 Webview 前端同时具备现代化构建与热更新体验，结合 Bun 的极速依赖管理与任务执行，让“打开即开发、F5 即运行”成为默认。

快速开始

• 依赖

  • Node.js 18+
  • Bun（推荐）
  • VS Code 或 CodeBuddy

• 安装与运行

  • 安装依赖：bun install
  • 开发（Webview）：bun run dev
  • 构建（扩展+Webview）：bun run build
  • 首次 F5 会自动检查并安装依赖，无需手工处理 node_modules

开发与调试

• 启动调试：VS Code 运行视图选择 “Debug Extension”，按 F5
• 预启动任务：
  • check-and-install-dependencies：检测/安装依赖（优先 Bun）
  • bun: dev 或 bun: build：运行开发或构建脚本
• 构建产物：
  • Webview：dist/webview
  • 扩展：由 @tomjs/vite-plugin-vscode 产出，package.json 指向 dist/extension/index.js

提示

• 如遇 Bun 阻止 postinstall（如 @swc/core），执行：
  • bun pm untrusted 查看被阻止包
  • bun pm trust @swc/core && bun install

项目结构

.
├── extension              # 扩展主逻辑（激活、命令、Webview入口）
│   ├── index.ts
│   ├── pluginManager.ts
│   └── views/
├── src                    # Webview 前端（React）
│   ├── main.tsx
│   ├── App.tsx
│   └── utils/
├── scripts
│   └── checkAndInstall.cjs  # F5 前依赖检查
├── .vscode
│   ├── launch.json          # extensionHost 调试配置
│   └── tasks.json           # bun: dev / bun: build / 依赖检查
├── vite.config.ts
├── package.json
└── tsconfig.json

架构与流程图

系统视图（扩展与 Webview 协作）

flowchart LR
  A[VS Code: Extension Host] -- 激活/命令 --> B[extension/index.ts]
  B -- 创建/管理 --> C[Webview Panel]
  C -- 加载 --> D[dist/webview/index.html + assets]
  D -- 与扩展通信 --> B

开发/构建流水线

sequenceDiagram
  participant Dev as Developer
  participant VS as VS Code
  participant Task as PreLaunch Tasks
  participant Bun as Bun
  participant Vite as Vite/Plugin

  Dev->>VS: F5 (Debug Extension)
  VS->>Task: preLaunchTask: check-and-install-dependencies
  Task->>Bun: bun install (必要时)
  Task->>Task: bun: dev / bun: build
  Task->>Vite: 统一构建扩展与 Webview
  Vite-->>VS: 输出 dist/webview & dist/extension
  VS-->>Dev: Extension Host 启动成功

依赖检查脚本（scripts/checkAndInstall.cjs）

• 功能

  • 检查 package.json 与 node_modules
  • 缺失依赖时优先使用 Bun 安装；否则回退 pnpm/yarn/npm
  • 输出带 [dep-check] 前缀的日志，并提供背景任务匹配标识

• 关键日志

  • [dep-check] 未发现 node_modules，需要安装依赖。
  • [dep-check] 检测到缺失依赖: react, ...
  • [dep-check] 依赖安装完成。
  • [dep-check] extension build start/success

常见问题排查

1. tsc: command not found

• 解决：确保 devDependencies 含 typescript；执行 bun install 后重试构建

2. Bun 阻止 postinstall（esbuild/SWC 相关）

• 操作：
  • bun pm untrusted
  • bun pm trust @swc/core
  • bun install
  • bun run build

3. 扩展激活失败：Cannot find module dist/extension/index.js

• 原因：扩展产物未生成或路径不一致
• 解决：
  • bun run build 后检查 dist/extension 是否存在
  • 对齐 package.json 的 main 与插件产物路径
  • 检查 vite.config.ts 的 @tomjs/vite-plugin-vscode extension 配置

设计建议

• 保持扩展与 Webview 的类型一致性（TypeScript）
• 模块化拆分，避免单文件过长（建议 < 500 行）
• 优先统一使用 Bun 运行脚本，避免 npm 混用导致环境差异
• 固定开发环境版本（Node/Bun），减少二进制兼容问题

致谢

• Bun（极速包管理与运行时）：https://bun.sh
• Vite（现代前端构建）：https://vitejs.dev
• React（前端框架）：https://react.dev
• @tomjs/vite-plugin-vscode（统一扩展与 Webview 构建）
• VS Code API（扩展开发接口）：https://code.visualstudio.com/api
• CodeBuddy（扩展宿主运行环境）
• 所有开源维护者与贡献者（社区的支持成就了本项目）

许可证

MIT