如何在effect-smol中用NodeRuntime和BunRuntime双启动Effect程序：新手完整指南

如何在effect-smol中用NodeRuntime和BunRuntime双启动Effect程序：新手完整指南

【免费下载链接】effect-smolCore libraries and experimental work for Effect v4项目地址: https://gitcode.com/GitHub_Trending/ef/effect-smol

effect-smol是 Effect v4 的核心库仓库，其中的@effect/platform-node与@effect/platform-bun两个平台包分别提供NodeRuntime和BunRuntime。两者用同一个runMain函数即可把你的 Effect 程序分别启动在 Node.js 或 Bun 上——一套业务代码，两种运行时，优雅关闭和错误报告自动搞定。本文带你快速掌握这套双启动机制。

🎯 一分钟认识 NodeRuntime 与 BunRuntime

对比项	NodeRuntime	BunRuntime
所属包	@effect/platform-node	@effect/platform-bun
源码位置	packages/platform-node/src/NodeRuntime.ts	packages/platform-bun/src/BunRuntime.ts
核心入口	NodeRuntime.runMain(program)	BunRuntime.runMain(program)
运行环境要求	Node.js ≥ 18	Bun

两个包的 API 形状完全一致，都只暴露一个runMain函数：把 Effect 程序作为进程主纤程（main fiber）运行，并自动接管进程生命周期。这也是"双启动"能成立的关键——你的程序本身不需要感知底层是 Node 还是 Bun。

📦 快速开始：一行代码启动

安装对应运行时包后，入口代码极其简单（示例摘自官方示例 ai-docs/src/01_effect/06_running/10_run-main.ts）：

import { NodeRuntime } from "@effect/platform-node" import { BunRuntime } from "@effect/platform-bun" import { Effect, Layer } from "effect" // 你的主程序（以 Layer 形式组织） const program = Layer.launch(Worker) // 在 Node.js 中启动 NodeRuntime.runMain(program) // 在 Bun 中启动，API 完全相同 BunRuntime.runMain(program)

实际项目中通常只会在部署时二选一：生产服务器用 Node，追求启动速度和本地开发体验选 Bun，业务代码零改动。

🧠 runMain 背后替你做了什么？

深入看共享实现 packages/platform-node-shared/src/NodeRuntime.ts，它基于核心包的 Runtime.makeRunMain 构建，帮你处理了四件烦心事：

1. 信号处理：自动监听SIGINT/SIGTERM（Ctrl+C 或服务管理器停止信号）；
2. 优雅关闭：收到信号时不直接杀进程，而是中断主纤程，让forkScoped派生的子纤程和所有带作用域的资源（连接、定时器、文件句柄）按顺序清理；
3. 退出码管理：成功为 0，失败非 0，且收到信号后一定会退出，不会"挂死"；
4. 错误报告：默认以友好的 "pretty" 格式打印错误日志，失败原因一目了然。

优雅关闭示例

官方示例中的 Worker 用Effect.forkScoped启动了一个每 1 秒打印日志的循环。按下 Ctrl+C 时：信号 → 中断主纤程 → 子纤程随作用域一起终止 → 进程干净退出，不会残留僵尸任务——这正是传统process.on("SIGINT")手写清理逻辑最容易出错的地方，而runMain帮你兜底了。

⚙️ 可选配置：3 个参数按需微调

runMain接受一个可选配置对象（参见 NodeRuntime.ts 源码注释）：

• disableErrorReporting: true——如果应用已有集中式错误上报，可关闭自动错误日志，避免重复打印；
• teardown——自定义最终化逻辑，例如根据退出原因生成不同的退出码，或在退出前执行收尾动作；
• disablePrettyLogger（Bun 文档中说明）——避免自动注入 pretty 日志器，方便接入自己的日志体系。

📂 相关源码与文档路径

• Node 运行时实现：packages/platform-node/src/NodeRuntime.ts
• Bun 运行时实现：packages/platform-bun/src/BunRuntime.ts
• 两者共享的信号处理核心：packages/platform-node-shared/src/NodeRuntime.ts
• 运行时抽象层（makeRunMain / Teardown）：packages/effect/src/Runtime.ts
• 双启动官方示例：ai-docs/src/01_effect/06_running/10_run-main.ts
• 若需从外部框架（如 Hono）调用 Effect，可改用 ManagedRuntime，示例见 ai-docs/src/04_integration/10_managed-runtime.ts

✅ 小结

在 effect-smol 中实现 Node/Bun 双启动只需记住三点：同一份runMainAPI、信号驱动的优雅关闭、可选的teardown定制退出行为。把程序写成 Layer，入口交给NodeRuntime.runMain或BunRuntime.runMain，进程生命周期就交给框架了。

【免费下载链接】effect-smolCore libraries and experimental work for Effect v4项目地址: https://gitcode.com/GitHub_Trending/ef/effect-smol