本文详解当运行 npm run build:watch（基于 nodemon + 构建工具链）时，为何浏览器无法加载页面，并指出关键误区：该命令仅监听文件变更并触发构建，不启动 Web 服务器；需手动提供服务才能在浏览器中访问 dist/ 目录下的静态资源。
本文详解当运行 npm run build:watch（基于 nodemon + 构建工具链）时，为何浏览器无法加载页面，并指出关键误区：该命令仅监听文件变更并触发构建，不启动 web 服务器；需手动提供服务才能在浏览器中访问 dist/ 目录下的静态资源。
你遇到的问题非常典型：终端中 npm run build:watch 运行成功、文件被自动重建、控制台输出流畅，但无论访问 localhost:3000 还是其他端口，浏览器始终空白或报错“连接被拒绝”。根本原因在于——这个脚本本身不提供 HTTP 服务。
从你的 package.json 脚本可见：
"build:watch": "nodemon -q -w assets/ --ext \".\" --exec \"npm run build\"", "build": "npm run build:scripts -s && npm run build:styles -s && npm run build:markup -s"
它只是用 nodemon 监听 assets/ 下的源文件变化，并反复执行构建流程。而构建目标（由 browserify、stylus、jade 共同完成）明确指向 dist/ 目录：
- browserify 输出 JS 到 dist/main.js（含 sourcemap）
- stylus 编译 CSS 到 dist/main.css
- jade 渲染 HTML 到 dist/index.html
✅ 此时，你的可访问站点实际已生成在项目根目录下的 dist/ 文件夹中，例如：
dist/ ├── index.html ├── main.a1b2c3d4.js ├── main.e5f6g7h8.css └── main.js.map
但浏览器无法直接打开 dist/index.html（因跨域限制且无服务支持 ES 模块/相对路径等），因此必须通过一个本地静态文件服务器来托管 dist/。
✅ 正确做法：启动一个轻量 HTTP 服务
推荐以下任一方式（无需额外配置）：
方式 1：使用 serve（最简快捷）
# 全局安装（仅需一次） npm install -g serve # 在项目根目录下，服务 dist 目录 serve -s dist
默认启动在 http://localhost:5000 —— 此时即可在浏览器中打开该地址查看效果。
方式 2：使用 http-server
npm install -g http-server http-server dist -p 8080
访问 http://localhost:8080
方式 3：集成进 npm script（推荐长期使用）
在 package.json 中添加：
"scripts": {
"build:watch": "nodemon -q -w assets/ --ext \".\" --exec \"npm run build\"",
"serve": "serve -s dist",
"dev": "npm-run-all --parallel build:watch serve"
}
然后运行：
npm install -g npm-run-all serve npm run dev
这将同时启动文件监听构建 + 静态服务，实现真正的“保存即刷新”开发体验。
⚠️ 注意事项
- ❌ 不要尝试直接双击 dist/index.html 或用 file:// 协议打开：现代前端资源（如模块化 JS、CSS @import、相对路径引用）依赖 HTTP 协议，否则会触发 CORS、MIME 类型错误或 404。
- ❌ nodemon 默认不启动服务器，它只是进程守护工具；即使你看到 listening on port 3000，也一定是其他脚本（如 express 服务）在运行——而你的当前脚本中并未包含此类逻辑。
- ✅ 始终确认 dist/ 目录存在且包含 index.html；若为空，请先手动执行一次 npm run build 排查构建脚本错误。
- ✅ 若使用 hashmark 生成带哈希的文件名（如 main.a1b2c3d4.js），请确保 index.html 中的 <script> 和 <link> 标签已通过 assets.json 动态注入正确路径（这是 jade 渲染阶段完成的，通常无需干预）。</script>
总结
npm run build:watch 是构建工作流的一环，而非开发服务器。它的职责是「响应变更 → 编译 → 输出到 dist/」；而「让浏览器能访问 dist/」是另一项独立任务——需要静态服务器支持。明确分工后，只需一条 serve -s dist 命令，即可打通从代码修改到页面预览的完整链路。
