code命令报错或无响应，90%因path未注册、用户数据目录损坏或gpu/扩展冲突；先验证code是否存在，再依次排查环境变量、--user-data-dir、--disable-gpu及--disable-extensions。
VSCode 命令行执行 code 报错或无响应，90% 不是安装损坏，而是 PATH 未注册、权限错乱、或用户数据目录损坏——先验证 code 命令是否存在，再逐层排除环境与配置问题。
code 命令根本不存在：PATH 未注册
这是新装 VSCode 后最常见的情况，终端输入 code 直接报 command not found。macOS 和 Windows 行为差异大，不能默认它已就绪。
- macOS：打开 VSCode → 顶部菜单栏
Code→Install 'code' command in PATH，执行后重启终端；若仍无效，检查~/.zshrc或~/.bash_profile是否漏加了export PATH="$PATH:/Applications/Visual Studio Code.app/Contents/Resources/app/bin" - Windows：安装时必须勾选
Add to PATH（默认不勾选）；若已安装，重装并勾选，或手动把C:\Users\<username>\AppData\Local\Programs\Microsoft VS Code\bin</username>加入系统环境变量的PATH - Linux（.deb/.rpm）：
code通常可用；但 Snap 安装版本（如 Ubuntu 软件中心默认）会因权限隔离导致code --user-data-dir等参数异常，建议卸载后改用官网.tar.gz包解压到~/apps/code并添加软链
code 命令存在但启动失败：用户数据目录损坏
能执行 code，但双击图标或运行 code . 后进程闪退、白屏、或卡在“Loading Extensions”，大概率是 ~/.vscode（Linux/macOS）或 %APPDATA%\Code（Windows）中某项缓存损坏。
- 临时跳过原目录验证：运行
code --user-data-dir="/tmp/vscode-clean"（Linux/macOS）或code --user-data-dir="D:\vscode-test"（Windows），若能正常打开，说明原目录损坏 - 不要直接删整个目录：先备份，再重命名原路径（如
Code-backup），让 VSCode 自建干净目录 - 迁移配置要谨慎：只复制
settings.json、keybindings.json等纯文本文件；避免复制Cache、GPUCache、Crashpad等二进制子目录
code 启动卡死或白屏：GPU/扩展/沙箱冲突
命令能执行、进程可见、但窗口不出或刚弹出就崩，基本锁定在 Electron 渲染层——GPU 加速、扩展宿主、或 Chromium 沙箱机制引发阻塞。
- 优先绕过 GPU：运行
code --disable-gpu，尤其适用于远程桌面、WSL2 GUI、老旧 Intel HD Graphics、或某些国产精简版系统 - 扩展问题确认：先
code --disable-extensions，若能进空界面，再用code --status观察输出末尾是否停在某个扩展名后；出现ERR! spawn ENOENT或Extension host terminated unexpectedly就是它 - 沙箱限制触发：Linux 下若报
Failed to move to new namespace，必须搭配--no-sandbox，即code --disable-gpu --no-sandbox；注意这只是排查手段，勿长期使用
Linux 下报 libXss.so.1 或 ICU 相关错误
这类报错不是 VSCode 本身问题，而是系统级依赖缺失或版本错配，常见于最小化安装发行版或系统升级后。
-
libXss.so.1: cannot open shared object file：Ubuntu/Debian 系统需手动安装依赖，运行sudo apt install libxss1 -
Invalid file descriptor to ICU data：本质是 Electron 内置 ICU 数据与系统libicu版本不兼容；典型于 Ubuntu 升级后，可尝试sudo apt install --reinstall libicu72（版本号按实际调整），或降级libicu包 - 别用
sudo code：曾用 root 权限启动会导致~/.vscode权限混乱，修复命令为chown -R $USER:$USER ~/.vscode，但切勿递归修改/usr/share/code
真正难排查的从来不是“打不开”，而是“看起来打开了却没反应”——比如进程在、CPU 在跑、DevTools 打得开，但欢迎页刷不出内容，或者终端里 code --status 卡在某行不动。这时候得盯住日志末尾那几行，而不是反复重装。
