必须用arm64原生版vscode，否则插件禁用、终端错乱、调试卡死；验证需三步：file命令查electron含arm64、process.arch返回arm64、活动监视器中code helper架构为apple silicon。
VSCode必须是ARM64原生版，否则一切配置都失效
不是“能打开就行”，而是必须验证底层架构。x86_64版本在M1/M2上会触发Rosetta 2转译，导致终端命令错乱、插件禁用、调试器卡死——这些现象背后全是架构不匹配。
验证方式有三个，缺一不可：
-
file /Applications/Visual\ Studio\ Code.app/Contents/MacOS/Electron输出里必须含arm64 - VSCode内按
Cmd+Shift+P→ 输入Developer: Toggle Developer Tools→ 控制台执行process.arch，返回值必须是"arm64" - 活动监视器中找到
Code Helper (Renderer)进程，“架构”列显示Apple silicon，不是Intel
官网下载页默认可能仍是Universal包，务必手动选择 macOS (ARM64) 版本（文件名含 darwin-arm64）。已装旧版需先 killall "Code Helper"，再双击启动，避免残留转译态。
终端和Node必须同为ARM64上下文
VSCode内置终端调用的是系统shell，如果它本身运行在x86_64下，node -v 就会报错或返回错误路径，后续所有调试、扩展、构建都会降级失败。
检查与修复步骤：
- 在VSCode内置终端中运行
uname -m，结果必须是arm64；若为x86_64，说明终端被Rosetta劫持 -
echo $SHELL应返回/bin/zsh（系统原生），而非/opt/homebrew/bin/zsh（若该zsh来自Intel Homebrew，就危险） - Homebrew必须重装ARM64版：卸载旧版
/usr/local/bin/brew，用官方脚本装到/opt/homebrew，否则which node指向的极可能是x86_64二进制
装完后确认：which node 返回路径如 /opt/homebrew/bin/node，且 node -v 在VSCode终端里能正常输出版本号。
launch.json里的program字段不能写相对路径字面量
断点灰掉、提示 Cannot launch program，90% 是因为 program 没指向一个真实可执行的 .js 文件——不是源码、不是文件夹、也不是没解析的相对路径。
正确写法只有一种推荐形式：
-
"program": "${workspaceFolder}/src/index.js"（跨平台安全，VSCode自动补全路径） - 错误写法：
"program": "src/index.js"（缺${workspaceFolder}/，VSCode不自动补前缀） - 错误写法：
"program": "./src/index.js"（.在这里不解析，等同字符串字面量）
TypeScript项目别直接指 src/index.ts；要么配 preLaunchTask 编译到 dist/ 后指 dist/index.js，要么改用 runtimeExecutable: "npx" + runtimeArgs: ["ts-node", "src/index.ts"]。
ESM项目必须声明"type": "module"
Node默认按CommonJS解析，遇到 import 就崩。这不是语法错误，是模块类型没对齐——VSCode调试器（pwa-node）和 code-runner 都依赖这个声明。
必须在项目根目录的 package.json 中显式写入：
{"type": "module"}
没声明就强行 import，断点可能命中但 require() 会失败，process.cwd() 行为也可能异常。若用 code-runner 插件，还需手动改其 executorMap，把 javascript 对应值设为 "node --experimental-specifier-resolution=node $fileName"。
最容易被忽略的其实是环境变量继承问题：从Dock或Spotlight启动VSCode，不会自动 source ~/.zshrc；必须彻底退出VSCode，再在终端执行 code . 启动，才能确保 PATH 和 node 路径被正确加载。
