开发与发布.md

FabNote 开发与发布说明

这份文档面向项目维护者，重点记录两件事：

• 怎么在本地调试和验证扩展
• 怎么更新版本号并打包 / 发布 VSIX

一句话说明

FabNote 本质上是一个 VS Code 扩展，加上一个运行在 Webview 里的 Vue 3 前端：

• 扩展端：仓库根目录，负责注册 .fbn 文件类型和 Custom Editor
• 前端端：webview-ui/，负责真正的编辑器界面
• 构建产物：webview-ui/ 构建后输出到根目录 media/

启动流程

最常用方式：按 F5 调试

日常开发时，推荐直接用 VS Code 的 F5 启动调试，而不是优先跑 yarn test。

注意：如果你改过 webview-ui/ 下的前端代码，必须先执行一次 yarn build，把最新产物写进根目录 media/，然后再按 F5。否则 Extension Development Host 里加载的还是旧页面。

操作步骤：

1. 用 VS Code 打开仓库根目录
2. 如果改过前端，先进入 webview-ui/ 执行 yarn build
3. 回到 VS Code 按 F5
4. 选择 .vscode/launch.json 里的 Run Extension
5. 等待新的 Extension Development Host 窗口打开

补充说明：

• F5 用来启动扩展调试，适合日常开发和手动验证
• yarn test 用来跑自动化测试，执行完成后会退出

首次安装依赖

根目录和 webview-ui/ 是两个独立的 Node 工程，需要分别安装依赖：

yarn
cd webview-ui
yarn

前端构建

FabNote 运行时读取的是根目录 media/，所以前端改动后需要先构建：

cd webview-ui
yarn build

这条命令会根据 ../webview-ui/vite.config.js 的配置，把产物直接输出到根目录 media/。

调试时怎么验证

在 Extension Development Host 里：

1. 打开或创建一个 .fbn 文件
2. 如果没有自动进入自定义编辑器，执行命令 Preview FabNote
3. 检查编辑、保存、另存、预览是否正常

常用命令

根目录

yarn lint
yarn test
npm run package:vsix

• yarn lint：检查扩展侧代码
• yarn test：运行 VS Code 扩展测试
• npm run package:vsix：自动升级版本号并打包 VSIX

webview-ui/

yarn dev
yarn build
yarn preview

• yarn dev：启动独立的 Vite 前端开发服务
• yarn build：构建并覆盖根目录 media/
• yarn preview：预览构建结果

打包 VSIX

仓库现在内置了一键脚本，可以自动更新根目录 package.json 的扩展版本号，然后执行 npx @vscode/vsce package。

默认用法

npm run package:vsix

默认会把当前版本按 patch 递增一次。比如：

• 0.0.6 会变成 0.0.7

指定版本号

npm run package:vsix -- 0.0.7

这会把根目录 package.json 里的 version 改成 0.0.7，然后执行打包。

直接调用脚本

脚本位置：

scripts/package-extension.ps1

也可以直接运行它：

powershell -ExecutionPolicy Bypass -File .\scripts\package-extension.ps1 -Bump minor
powershell -ExecutionPolicy Bypass -File .\scripts\package-extension.ps1 -Version 0.1.0

支持的自动递增级别有：

• patch
• minor
• major

只更新版本，不真正打包

如果你只想验证版本更新逻辑，或者暂时不想生成新的 .vsix 文件：

powershell -ExecutionPolicy Bypass -File .\scripts\package-extension.ps1 -Version 0.0.7 -SkipPackage

手动打包命令

如果你不想用脚本，底层仍然可以手动执行：

npx @vscode/vsce package

执行完成后会在仓库根目录生成类似：

fabnote-0.0.7.vsix

安装本地 VSIX：

code --install-extension fabnote-0.0.7.vsix

发布到 VS Code Marketplace

如果你的 Publisher 和 Personal Access Token 已经配置好：

npx @vscode/vsce publish

如果这是首次在本机发布，先登录：

npx @vscode/vsce login CreatorSN

建议发布流程

推荐优先使用现在的一键脚本：

1. 在 webview-ui/ 执行 yarn build
2. 回到根目录执行 yarn lint
3. 可选执行 yarn test
4. 执行 npm run package:vsix，或 npm run package:vsix -- 0.0.7
5. 确认生成的 VSIX 可安装、可打开、可保存
6. 再执行 npx @vscode/vsce publish

如果你更喜欢手动流程，也可以继续这样做：

1. 手动更新根目录 package.json 里的 version
2. 在 webview-ui/ 执行 yarn build
3. 回到根目录执行 yarn lint
4. 可选执行 yarn test
5. 执行 npx @vscode/vsce package
6. 确认无误后执行 npx @vscode/vsce publish

容易忘的点

• 扩展实际加载的是根目录 media/，不是 webview-ui/src/
• 前端改完如果没执行 yarn build，VS Code 里看到的通常还是旧界面
• .vscode/launch.json 已经配置好调试入口，不需要额外写启动脚本
• 现在根目录 package.json 已提供 npm run package:vsix，常规打包优先用它即可

关键文件

• package.json：扩展元信息、命令、文件类型、发布者
• extension.js：扩展激活、自定义编辑器、保存逻辑
• scripts/package-extension.ps1：版本升级与 VSIX 打包脚本
• webview-ui/vite.config.js：前端打包到 media/ 的关键配置
• .vscode/launch.json：F5 调试入口