vsce package 必须在含 package.json 的插件根目录执行，否则报“Cannot find package.json”；需确保 README.md 首行为有效标题、engines.vscode 符合语义化范围（如"^1.83.0"），路径避免中文/空格。
vsce package 命令必须在插件根目录下执行
直接在任意路径敲 vsce package 会报错“Cannot find package.json”，因为工具依赖项目根目录下的 package.json 和 extension 目录结构。确认当前工作目录是插件源码顶层（含 package.json、README.md、src/ 等），再运行命令。
常见错误现象：ERROR No extension files found 或 WARNING README.md contains 'README' —— 后者不是致命错误，但会导致打包失败（vsce 默认校验 README 内容不能只写 “README”）。
- 临时绕过 README 检查：用
echo "# My Extension" > README.md替换空文件或占位内容 - 若用 PowerShell，避免路径含中文或空格；推荐在 Git Bash 或 WSL 中执行
- 不加参数时，
vsce package会读取package.json中的version字段生成文件名，如my-ext-1.2.3.vsix
package.json 的 engines.vscode 字段决定最低兼容版本
这个字段写错会导致 .vsix 在旧版 VS Code 上静默失效——不报错、不加载、也不提示。比如你填 "^1.85.0"，那 VS Code 1.84.x 及更早版本装了也不会激活扩展。
- 建议设为当前主力版本减两个 minor 版本，例如你用 1.85.2，就填
"^1.83.0" - 字段值必须是语义化版本范围（如
"^1.70.0"或=1.65.0 ），不能写成"1.85"这种固定值 - 如果插件用了新 API（如 Webview UI Toolkit），需同步检查该 API 的首次引入版本，并据此调整
engines.vscode
打包后 .vsix 打不开？先看签名和压缩完整性
双击无反应，或拖进 VS Code 提示 "Extension is not signed"，多数不是签名问题，而是 ZIP 结构损坏或顶层目录缺失。
用 unzip -l my-ext-1.2.3.vsix 查看内容：正常应有 [Content_Types].xml、extension.vsixmanifest、extension/ 目录；如果只有 package.json 平铺在根层，说明 vsce 没识别到扩展源码目录。
- 确保
package.json中"main"字段指向编译后的 JS 入口（如"./out/extension.js"），且该文件真实存在 - 若用 TypeScript，必须先
npm run compile或npm run watch生成out/目录，否则vsce package会打包空逻辑 - Windows 下用
--no-yarn参数可跳过 yarn.lock 校验，避免因本地没装 yarn 导致失败
离线安装 .vsix 的三种方式，成功率差异明显
拖拽安装最稳，命令行次之，手动解压复制最易出错——不是功能不行，而是 VS Code 启动时校验逻辑严格。
- 拖拽：把未解压的
.vsix文件直接拖到 VS Code 编辑区中央（非侧边栏、非设置页），松手即弹确认框；失败时先检查 VS Code 是否获得焦点、是否处于远程 SSH 状态 - 命令行：
code --install-extension /absolute/path/to/my-ext-1.2.3.vsix，Windows 上路径务必用正斜杠，如C:/dev/my-ext/my-ext-1.2.3.vsix - 手动复制：先
unzip -l my-ext-1.2.3.vsix看顶层目录名（如john.doe.my-ext-1.2.3/），再完整复制该目录到~/.vscode/extensions/（Linux/macOS）或%USERPROFILE%\AppData\Roaming\Code\Extensions\（Windows）；漏掉外层目录名或放错位置，VS Code 启动时直接忽略
真正容易被忽略的是 engines.vscode 和 main 路径的匹配关系：前者控制“能不能装”，后者决定“装了有没有逻辑”。两者不一致，就会出现插件显示已启用、但所有命令都找不到的情况。
