VSCode插件因版本不兼容被静默禁用，需执行code --version获取纯数字版本号，比对插件package.json中engines.vscode声明的语义化范围；不匹配则插件加载阶段即被拒绝，无日志输出。
VSCode 版本兼容性问题，90% 出现在插件加载阶段，而不是运行时报错；只要 code --version 输出的版本号不满足插件 package.json 中 engines.vscode 字段声明的范围，插件就会被静默禁用——连控制台日志都不会出现。
怎么看当前 VS Code 版本是否达标
打开终端（任意位置），直接执行：
code --version
输出类似 1.118.0 这样的纯数字版本号。注意：这不是“关于”窗口里带括号的完整字符串（如 1.118.0 (user setup)），VS Code 内部校验只认前者。
- 若命令报
command not found或'code' is not recognized，说明安装时没勾选“添加到 PATH”，需重装或手动配置环境变量 - Windows 用户别依赖资源管理器右键菜单里的“在此处打开终端”，它可能继承旧 shell 环境，导致
code不可用 - macOS/Linux 下，如果
which code返回空，检查是否用了code-insiders（内测版），它的命令名不同
插件报 “not compatible” 时怎么快速定位原因
错误信息里写的 not compatible with VS Code '1.xxx' 并不是说你装错了插件，而是插件包里 extension/package.json 的 engines.vscode 值和你本地版本不匹配。VS Code 启动时就拒绝加载，根本不会进初始化逻辑。
- 在扩展面板中找到该插件 → 点击右下角
⋯→Copy Extension ID（如FittenTech.Fitten-Code） - 打开命令面板（
Ctrl+Shift+P），运行Developer: Toggle Developer Tools - 在控制台中粘贴并执行：
vscode.extensions.getExtension("FittenTech.Fitten-Code")?.packageJSON.engines.vscode，输出类似"^1.103.0"就是它实际声明的兼容范围 - 对比
code --version输出值是否落在该语义化范围里（例如1.118.0满足^1.103.0，但不满足^1.120.0）
离线改 .vsix 文件绕过版本校验的实操要点
.vsix 本质是 ZIP 包，修改关键字段比找历史版本快得多，但细节错一步就装不上。
- 必须用专业解压工具（
7-Zip/unzip/ macOSArchive Utility），别用 Windows 资源管理器双击解压——会破坏 ZIP 结构，重打包后 VS Code 拒绝识别 - 解压后进入
extension/package.json（不是根目录那个），只改"engines": { "vscode": "..." }这一行，推荐写成"vscode": ">=1.75.0"，避免未来升级再出问题 - 重打包时，确保压缩的是整个
extension/文件夹内容（不要把extension文件夹本身也打进去），否则路径错位，插件找不到入口文件 - 安装后务必完全退出 VS Code（包括托盘进程），否则旧缓存仍生效，locale、插件状态等都可能不刷新
为什么改完 engines 还是没反应
常见于中文包、Fitten Code 等依赖语言或远程组件的插件。版本过了只是第一步，后续还有两层校验：
- locale 配置未生效：检查
%APPDATA%\Code\User\locale.json（Windows）或~/Library/Application Support/Code/User/locale.json（macOS），内容必须是精确的{"locale": "zh-hans"}，多空格、少引号、写成zh-CN都无效 - Remote-SSH 或 WSL 场景下，远端自动拉取的
vscode-server版本必须和本地严格一致；code --version是1.118.0，远端却跑着1.117.1的 server，连接就会卡在Starting VS Code Server - 插件启用状态是假象：即使 UI 显示“已启用”，执行
console.log(!!vscode.extensions.getExtension("xxx")?.isActive)返回false，说明它被引擎拦截后从未真正激活过
