vsce package 可直接生成 .vsix 文件,但初学者常因未全局安装 vsce、package.json 中 engines.vscode 版本不匹配(须 ≥ 当前 VS Code 版本)、main 字段指向的入口文件不存在(需先编译)、或 README.md 为空/命名错误而失败。

直接用 vsce package 就能生成可安装的 .vsix 文件,但多数初学者卡在环境没配对、package.json 版本不匹配、或 README.md 校验失败这三处。
vsce 工具必须全局安装且版本兼容
vsce 是官方打包工具,不是可选插件——它负责读取 package.json、编译源码(如果用了 TypeScript)、校验字段、生成压缩包。没装它,npm run package 也跑不起来(除非你手动配置了等效脚本)。
- 运行
npm install -g vsce安装;Windows 用户若报权限错误,加--location=global - 装完执行
vsce --version,确认输出不是command not found - VS Code 当前版本(2026 年 10 月稳定版是
1.118.x)必须 ≥package.json中"engines": {"vscode": "^1.118.0"}的最低要求,否则vsce package直接报错退出
package.json 的 engines 和 main 字段必须真实有效
这两个字段是打包时的硬性检查点,错一个就停。
-
"engines": {"vscode": "^1.118.0"}:不能写成"^1.87.0"或留空;查自己 VS Code 版本的方法是打开帮助 → 关于,看第一行数字 -
"main": "./out/extension.js":如果你用的是 TypeScript,默认构建输出到out/目录;如果没运行过tsc -p ./或npm run compile,这个文件根本不存在,vsce会提示Extension entry point not found - 改完
package.json后必须重新运行编译命令(如npm run compile),不能只改 JSON 就打包
README.md 不是摆设,但可以极简绕过校验
vsce package 默认强制检查 README.md 是否含有效内容,否则报 ERROR Make sure to edit the README.md file...。这不是发布限制,而是打包时的 lint 规则。
- 正式发布前当然要写完整,但本地测试阶段,只需让文件“不为空且不含纯 README 字符串”即可
- 执行
echo "# My Extension" > README.md(Linux/macOS)或echo # My Extension > README.md(PowerShell)就能通过 - 别删掉
README.md文件本身——vsce会直接报找不到文件 - 注意文件名大小写:必须是
README.md,不是readme.md或Readme.md
真正容易被忽略的是:每次改完 src/extension.ts 后,如果没重新编译,.vsix 里打包的还是旧的 out/extension.js——你看到的“更新没生效”,大概率是这个原因,而不是插件逻辑有问题。











