必须先在系统原生命令行执行node -v和npm -v验证版本号，若报错说明PATH未生效，需重装Node并勾选“Add to PATH”或手动修正路径，之后彻底退出VSCode再重启，内置终端成功识别后方可进行后续调试或服务配置。
node -v 报错就别往下看了
VSCode 里跑不起来 Node.js 静态服务，90% 是因为 node 命令根本不可用。不是插件没装、不是配置不对，是连解释器都找不到。
必须在系统原生命令行（Windows 的 cmd/PowerShell、macOS/Linux 的 Terminal）里执行：node -v 和 npm -v，两个都得输出版本号。如果报“不是内部或外部命令”，说明 PATH 没生效——安装时没勾选 Add to PATH，或者手动加路径时复制错了、路径含中文或空格（比如 C:Program Files
odejs 就不行，C:
odejs 才安全）。
- 改完环境变量后，必须彻底退出 VSCode（右上角 × 关掉所有窗口），再重新打开
- 不要依赖 Code Runner 插件启动静态服务：它不读
package.json的"type": "module"，也不加载.env，容易在 import/export 场景下直接崩 - 验证方式：在 VSCode 内置终端（
Ctrl + `）里再跑一遍node -v，成功了才继续
用 http-server 还是 express.static？
本地静态资源服务不需要写完整后端逻辑，但选错工具会多踩一堆坑。
http-server 是零配置 CLI 工具，适合纯 HTML/CSS/JS 项目快速预览；express.static 更灵活，能加中间件、处理路由 fallback、兼容 package.json 的 exports 字段，但需要写几行 JS。
- 如果只是预览构建产物（如
dist/目录），直接全局或本地装http-server：npx http-server ./dist -p 3000 -c-1（-c-1禁用缓存，避免刷新看不到新文件） - 如果项目已用 Express 或需要 SPA 路由 fallback（比如 React/Vue 的 history 模式），用
express.static：const express = require('express'); const app = express(); app.use(express.static('./dist')); app.get('*', (req, res) => res.sendFile('./dist/index.html')); app.listen(3000); - 注意 Node.js 版本差异：Node 20+ 默认启用 ESM，若用
import语法，文件后缀必须是.mjs或package.json明确设"type": "module"，否则require('express')会报错
launch.json 里 runtimeExecutable 不写等于没配
调试静态服务时断点不触发、console.log 不输出、甚至进程直接退出，大概率是 VSCode 调用了错误的 Node.js 版本。
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
尤其当你用 nvm/nodenv 管理多版本，或系统自带一个 Node、nvm 安装另一个，VSCode 的调试器和终端看到的 node 可能不是同一个。
- 在项目根目录建
.vscode/launch.json，关键字段必须显式指定："runtimeExecutable": "/usr/local/bin/node"（macOS/Linux）或"runtimeExecutable": "C:\nodejs\node.exe"（Windows） - 验证是否生效：在调试脚本里加
console.log(process.execPath)，对比输出路径和runtimeExecutable是否一致 - 别漏掉
"env": { "NODE_ENV": "development" }——某些静态服务库（如serve）靠这个判断是否启用热重载
tasks.json 启动服务时 npm run serve 失败的真相
tasks.json 里直接写 "command": "npm run serve" 几乎必挂，不是脚本写错了，是 VSCode 的任务环境根本不加载你的 shell 配置。
它不读 ~/.zshrc，不继承 PATH，也不自动把 node_modules/.bin 加进可执行路径，所以 cross-env、serve、http-server 全部 command not found。
- 正确写法是用
npx --no-install直接调本地包："command": "npx --no-install http-server ./dist -p 3000" - 显式指定 shell：
"shell": { "executable": "/bin/zsh", "args": ["-c"] }（macOS/Linux）或"shell": { "executable": "cmd.exe", "args": ["/c"] }（Windows） - 补全 env：
"env": { "PORT": "3000", "NODE_ENV": "development" }，避免服务监听默认端口被占 - 确保
tasks.json在项目根目录的.vscode/下，且每个 task 有"label"和"type": "shell"，否则 Ctrl+Shift+P → Tasks: Run Task 里压根看不到它
静态服务本身很简单，难的是让 VSCode 的各个子系统（终端、调试器、任务）用同一套环境变量和 Node 版本。路径、shell、runtimeExecutable、npx —— 漏掉任何一个，都可能卡在“为什么明明能跑，就是调试不了”这种问题上。
