serveRoot · watch · onChangeCommand
把预览链路
交给一个二进制
watchpreview 接管前端开发里最繁琐的一段：监听源码、触发编译、起静态服务、通知浏览器刷新。框架只需要 spawn 一个命令、读 stdout 拿 URL。
$watchpreview preview --config config.json
下载二进制 →
PIPELINE
单实例幂等键：serveRoot（规范化后）
Windows / macOS / Linux 行为一致
01
为什么需要它
每个前端框架的开发工具都在各自重复实现同一段链路。watchpreview 把它抽成一个与框架无关的基础设施二进制，一份 JSON 配置即可委托。
没有 watchpreview
- 自己实现文件监听与防抖
- 自己 spawn 编译进程、处理失败
- 自己起静态服务、管理端口
- 自己写浏览器刷新协议
- 多进程重复启动，端口冲突
有了 watchpreview
- spawn 一个命令，读 stdout 拿 URL
- watch + onChangeCommand 交给它编排
- serveRoot 幂等，同目录自动复用实例
- 成功才刷新，失败保留旧页面
- 三端行为一致，跨平台编译发布
02
快速使用
从零配置的静态预览，到委托编译的全自动链路，配置只增不改结构。
# 以当前目录为静态服务并监听变化 watchpreview # → http://127.0.0.1:54231/
// config.json { "serveRoot": "dist" } # 只 serve 某个目录 watchpreview preview --config config.json
// config.json { "serveRoot": "dist", "watch": ["src"], "onChangeCommand": "npm run build" } # 源码变 → build → dist 自动刷新 watchpreview preview --config config.json
const { stdout } = await execFileAsync( "watchpreview", ["preview", "--config", wpPath] ); // 契约：首行即 URL const url = stdout.split(/\r?\n/) .find(l => l.trim())?.trim();
03
配置字段
所有路径相对 config 所在目录（也接受绝对路径）。
| 字段 | 必填 | 说明 |
|---|---|---|
| serveRoot | 是 | 被服务的 dist 目录（幂等键）；缺省 --config 时为当前工作目录 |
| watch | 否 | 源码监听根，可多个，递归；有 onChangeCommand 时生效 |
| exclude | 否 | 路径前缀过滤；内置忽略 .git、node_modules、点开头目录 |
| onChangeCommand | 否 | 编译命令，非空即启用"源变 → 编译 → 刷新"管道 |
04
集成契约
watchpreview preview 的 stdout 只有一行 URL，其余一切走 stderr。四条硬规则：
规则 01
stdout 只有那一行 URL，无多余输出
规则 02
每次以本次 stdout 为准；同 serveRoot 二次调用一定复用同一 URL
规则 03
失败 ≠ 重试信号；非零即失败，陈旧状态自动重启属正常自愈
规则 04
同一 serveRoot 只维护一个实例，多进程需自行串行化调用
05
安装
goreleaser 跨平台编译，挂载到 GitHub Release，自动附 checksums.txt。
linux
amd64 / arm64
darwin
amd64 / arm64
windows
amd64 / arm64