Windmill 本地预览工作流完全指南wmill dev 直连/代理双模式、launch.json 集成与源码级原理【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill本指南以 Windmill 开源仓库中的system_prompts/base/preview.md为骨架系统讲解如何利用wmill dev与wmill app dev在本地即时预览 flow流程图、script脚本编辑器与 app应用涵盖「直连 vs 代理」双模式选型、谁启动服务器的两种路径手动后台启动 /.claude/launch.json驱动的 MCP 预览、三种命令行的输出行形态以及不部署、无副作用的非可视化替代命令wmill flow preview与wmill script preview。读完你将能根据嵌入端浏览器标签、IDE 预览面板、Claude Desktop/Code MCP正确选择拓扑并可靠地把 URL 交给用户或嵌入器同时理解这些行为背后 CLI 源码的实现逻辑。一、预览工作流是什么Windmill 的开发页面dev page渲染 flow 的流程图或 script 的编辑器允许用户逐步查看步骤step through steps并且每次保存都会实时刷新live-reload。它通过wmill dev在本地运行最终通过 localhost 端口访问。与wmill sync push部署到远程工作区不同预览是只读、不部署的。这一点在命令定义中有明确注释Watch local file changes and live-reload the dev page for preview. Does NOT deploy to the remote workspace — use wmill sync push for that.见 cli/src/commands/dev/dev.ts也就是说你在本地编辑、预览、验证确认无误后再决定是否推送到远程全程不会污染生产工作区。凡是看到、打开、导航到、可视化、预览某个 flow/script/app的需求或刚写完一个对象想获得可视化验证时都应走这套预览流程。二、两个相互独立的决策wmill dev的用法由两个维度组合而成两个决策互不依赖需要分别做出选择。决策一代理模式Proxy还是直连模式Direct选择依据是最终展示预览的那个宿主需要什么类型的 URL。代理模式--proxy-port port在http://localhost:port/暴露开发页面。适用于你交付 URL 的嵌入器只接受 localhost URL的场景——大多数 IDE 内预览、聊天式预览嵌入器都是如此因为它们对跨域加载做了沙箱限制。直连模式默认用户浏览器直接从远程工作区的 HTTPS URL加载开发页面本地wmill dev只运行 WebSocket 回程通道用于 live-reload。适用于 URL 会在普通浏览器标签页中打开的场景。默认选择直连模式除非你明确遇到了需要 localhost 的嵌入器。原文档强调Never start the proxy just in case —— 当没有嵌入器需要 localhost 时代理只是多一跳无意义的开销。决策二谁启动服务器你自己后台启动手动 spawnwmill dev …或wmill app dev …捕获它打印的 URL然后进行下一步打开标签页、把 URL 交给嵌入器。运行时根据.claude/launch.json启动某些运行时目前是 Claude Desktop / Claude Code 的 MCP 预览集成即工具名前缀带mcp__Claude_Preview__的工具能读取launch.json配置在你调用它们的预览工具时按需启动开发服务器。只有当你确实拥有这样的工具时才走这条路——否则没有任何东西会读这个文件wmill dev永远不会启动。两个决策的组合矩阵嵌入端需要 localhostlaunch.json 运行时应该怎么做普通浏览器标签页否不适用直连模式你自己启动把 URL 给用户接受任意 URL 的 IDE / 聊天预览面板否否直连模式你自己启动把打印出的 URL 指向嵌入器只接受 localhost 的 IDE / 聊天预览面板是否代理模式你自己启动把http://localhost:port/指向嵌入器Claude Desktop / Code MCP 预览是是代理模式写一条launch.json条目调用 MCP 工具三、自己启动服务器无 launch.json 运行时当没有 launch.json 感知的运行时可用时无论哪种模式都由你手动启动。命令是长驻进程long-running必须在后台启动不要阻塞等待。flow / script 的预览命令# 直连模式 —— 得到远程开发页面的 URL wmill dev --path wmill_path --no-open # 代理模式 —— 得到 302 到远程开发页面的 localhost URL wmill dev --proxy-port 4000 --path wmill_path --no-open各参数含义与 cli/src/commands/dev/dev.ts 中的命令行定义一一对应--path path监视指定的 windmill 路径如u/admin/my_script或f/my_flow。省略时开发页面会显示一个选择器picker供你在页面上挑选要预览的 flow 或 script。--proxy-port port:number本地 localhost 反向代理端口代理转发到远程 Windmill 服务器。--no-open不自动打开浏览器。--includes pattern...按 glob 模式或路径过滤被监视的文件可选。app 的预览命令cd app_path__raw_app wmill app dev --no-open --port 4000wmill app dev必须在*__raw_app文件夹内运行或将其作为参数传入且该文件夹必须包含raw_app.yaml否则命令会直接报错退出见 cli/src/commands/app/dev.ts。它从 app 文件夹运行没有--path参数——app 路径来自raw_app.yaml中的custom_path字段。默认端口为4000默认宿主为localhost见 cli/src/commands/app/dev.ts。捕获并传递 URL三种输出行形态每条命令都会在 stdout 打印 URL但行形态不同捕获时要区分wmill dev --no-open直连打印Go to url其中url是完整的远程 URL已内置 workspace、token、path。wmill dev --proxy-port打印Dev proxy listening on http://localhost:port—— 交给嵌入器的 URL 是http://localhost:port/。wmill app dev --no-open打印 Dev server running at url—— 本地 app 服务器地址。捕获 URL 时用宽松匹配启动输出中第一个https?://…的 token然后交给嵌入器或转述给用户Preview is running —— openurlin your browser.。不要自己拼接 URL你没有 workspace ID 和认证 token构造出来的地址无效。为什么不能自己构造 URL从源码可以清楚看到 URL 的组成直连模式下wmill dev会打印形如${workspace.remote}dev?workspace${workspace.workspaceId}localtruewm_token${workspace.token}port${port}path${path}的地址见 cli/src/commands/dev/dev.ts代理模式下根路径/会 302 重定向到/dev?workspace...localtruewm_token...port...path...见 cli/src/commands/dev/dev.ts。workspace.workspaceId与workspace.token都来自本地登录态解析手工拼接必然缺失这些关键参数。输出中的附加信息指定了--path时还会打印Watching path — edits will live-reload in the dev page未指定时打印Open the dev page and pick a flow or script to preview — edits will live-reload与(pass --path path to skip the picker)直连模式下 WebSocket 服务监听在ws://localhost:3001/ws默认端口PORT 3001见 cli/src/commands/dev/dev.ts 与 cli/src/commands/dev/dev.ts。四、让 launch.json 启动服务器仅 Claude Desktop / Code MCP仅当你的工具列表中存在mcp__Claude_Preview__*的 MCP 工具时才走这条路。否则跳过本小节——没有 MCP 工具读取文件wmill dev永远不会启动。每个 flow / script / app 都要有各自独立的命名条目写入用户的.claude/launch.json这样多个预览可以共存而不互相冲突——每条条目钉住不同的端口与路径。绝不为不同目标复用一个通用的 windmill 条目。第一步复用或新增 per-target 条目命名约定windmill: wmill_path例如windmill: f/test/my_flow。条目已存在→ 直接复用记下它的port供下一步使用。不存在→ 新增一条。选择一个未被其他条目占用的端口从 4000 开始递增。形态如下flow / script 的条目{ name: windmill: f/test/my_flow, runtimeExecutable: bash, runtimeArgs: [-c, wmill dev --proxy-port ${PORT:-4000} --path f/test/my_flow --no-open], port: 4000, autoPort: true }app*__raw_app/的条目wmill app dev是等价物——从 app 文件夹运行、没有--path{ name: windmill: f/test/my_app, runtimeExecutable: bash, runtimeArgs: [-c, cd f/test/my_app__raw_app wmill app dev --no-open --port ${PORT:-4001}], port: 4001, autoPort: true }如果.claude/launch.json还不存在用标准 shell 结构创建{ version: 0.0.1, configurations: [...] }。注意两条条目都运行在代理模式下--proxy-port因为 Claude 的端口检测预览需要 localhost origin。这也和组合矩阵中Claude Desktop / Code MCP 预览 → 代理模式的结论一致。第二步调用 MCP 预览工具把 MCP 预览工具指向刚添加/找到的条目。URL 使用http://localhost:port/——代理在/处的重定向会自动附加 workspace ID、认证 token 和路径。不要自己构造/dev?...形式的 URL。MCP 工具会按需启动该配置因此你无需手动启动wmill dev进程。五、非可视化替代wmill flow preview / wmill script preview如果用户想要的是程序化测试而不是可视化预览使用以下命令。两者都会打印任务结果可以放心自己运行并且不部署# flow运行整个流程的本地预览 wmill flow preview path -d args # script预览本地脚本而不部署 wmill script preview path -d args从源码看wmill script preview的命令定义为 preview a local script without deploying it. Supports both regular and codebase scripts.支持-d/--dataJSON 字符串或filename/-stdin 传参、-s/--silent只输出最终结果适合脚本化、--tag覆盖 worker tag等选项见 cli/src/commands/script/script.ts。wmill flow preview则先做本地 PathScript 替换再调用runFlowPreview启动任务并轮询结果见 cli/src/commands/flow/flow.ts。它还支持--step step_id只运行流程中指定步骤而不是整个 flow见 cli/src/commands/flow/flow.ts--data在该模式下作为该步骤的参数预览默认使用本地 PathScript 文件加--remote可改为预览已部署的远程脚本见 cli/src/commands/flow/flow.ts。六、源码级原理两种模式在 CLI 中的实现直连模式最简拓扑纯 WebSocket 通道startDirectServer是最简的拓扑——一个裸 WebSocket 服务器见 cli/src/commands/dev/dev.ts浏览器从远程工作区 URL 加载开发页面页面通过localtrue参数识别本地回程打开 WebSocket 连到ws://localhost:port/ws本地文件变更经文件监视器fs.watch触发broadcastChanges把最新编辑推送给所有已连接客户端。端口绑定前会做双栈探测resolveBindPort同时探测 IPv4 与 IPv6若请求端口在任一栈被占用则向上寻找下一个空闲端口避免与残留的 dev server 静默冲突见 cli/src/utils/port-probe.ts。代理模式localhost 反向代理 WebSocket 升级startProxyServer运行一个 localhost HTTP 服务器见 cli/src/commands/dev/dev.ts承担两类职责HTTP 转发根路径/302 到/dev?workspace...localtruewm_token...port...path...其余路径原样转发到远程服务器host头替换为远程 hostset-cookie的domain被重写为localhost这样 cookie 才能作用于本地 origin。WebSocket 升级/ws_dev与/ws就地交给本地 dev WebSocket 处理器live-reload 通道/ws/...、/ws_mp/...、/ws_debug/...等前缀则代理到远程wss/ws地址实现双向消息透传。代理模式下打印的正是Dev proxy listening on http://localhost:port见 cli/src/commands/dev/dev.ts。消息协议与编辑回写开发页面与本地服务器通过 WebSocket 交换 JSON 消息见 cli/src/commands/dev/dev.tsload按路径加载并广播某个文件的编辑flow把页面上的流程编辑回写磁盘flow.yaml 与内联脚本提取带 200ms 防抖以避免打字过程中的竞态loadWmPath按 windmill 路径加载 flow/script同时支持.flow与__flow两种文件夹后缀listPaths列出工作区中所有可预览的 flow/script/raw_app 条目供页面上的选择器使用。broadcastChanges受--path门控设定了--path时只广播与该路径匹配的编辑避免无关文件的改动打扰当前预览视图见 cli/src/commands/dev/dev.ts。wmill app dev 的差异化实现wmill app dev与wmill dev是两条独立的命令。它运行在*__raw_app文件夹内用 esbuild 做本地打包含 Svelte/Vue 框架插件与虚拟wmill模块通过 SSE 端点/__events通知浏览器刷新见 cli/src/commands/app/dev.ts 与 cli/src/commands/app/dev.ts。它还会监视backend/下的 runnable 文件并增量推断参数 schema500ms 防抖见 cli/src/commands/app/dev.ts以及提供 SQL 迁移确认弹窗和可选的会话录屏--recording能力。这就是 Dev server running at 背后发生的事情。七、反模式清单务必避免❌ 在工具列表中没有mcp__Claude_Preview__*工具时仍写.claude/launch.json条目。没有任何东西会读这个文件服务器永远不会启动。此时应自己 spawnwmill dev。❌ 没有嵌入器需要 localhost URL 却启动代理。直连模式才是正确选择——代理只是无目的的额外开销。❌ 为每个预览目标复用一个通用launch.json条目。每个 flow/script/app 都应该有自己的命名条目、自己的端口——这是多个会话共存、互不覆盖的机制。❌ 修改既有条目的--path来重新指向目标。应该新增条目。❌ 自己构造http://localhost:port/dev?pathX。代理的/重定向负责附加 workspace ID 与认证 token绕过它得到的是损坏的页面。始终使用http://localhost:port/。❌ 在前台启动wmill dev会挂起。始终后台运行。❌ 把在 IDE 面板打开和在浏览器打开同时列为菜单选项。根据上下文二选一。八、决策速查拿到预览需求后先问自己展示方接受的 URL 是什么形态localhost → 代理模式任意 URL → 直连模式默认。再问有没有mcp__Claude_Preview__*工具有且是 Claude 生态 → 走 launch.json MCP否则你自己后台启动并捕获 URL。若要程序化验证而非可视化 → 用wmill flow preview/wmill script preview不部署、打印任务结果。无论哪种路径URL 一律以命令输出为准绝不手工拼接。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考