如何在macOS的M1芯片上为VSCode配置Node环境

在M1/M2芯片的Mac上配置VSCode的Node环境，看起来简单，但坑真不少。最关键的一点是什么？

必须用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，并且在VSCode终端里 node -v 能正常输出版本号。

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，将 ja vascript 对应的值设为 "node --experimental-specifier-resolution=node $fileName"。

最容易被忽略的其实是环境变量继承问题：从Dock或Spotlight启动VSCode，不会自动执行 source ~/.zshrc。必须彻底退出VSCode，再在终端里执行 code . 启动，才能确保 PATH 和 node 路径被正确加载。这一点，往往是很多“疑难杂症”的根源所在。