Effect 4.0 发布：TypeScript 效应系统的 LTS 大版本

Effect 4.0 已于 10 月 1 日发布在 npm 与 GitHub。这是 TypeScript 生态里效应系统（effect system）库 Effect 的第一个 LTS 大版本：核心包零运行时依赖，整个生态统一到单一版本号，官方同时给出了一份写到 2029 年的支持时间表。对把生产系统押在它上面的团队来说，这次发布的分量不在新增了几个 API，而在工程承诺落地了。

三组基准数字

官方公告给出一组 3.x 与 4.x 的同源对比数据：相同源码构建、压缩加 gzip，运行数据取九次全新进程的中位数。

三组数字对应同一次底层重写：fiber 运行时被推倒重做，内存开销和执行路径都重新设计过。并发吞吐提升 6.4 倍意味着高并发场景下同样的硬件能承载更多任务；5 万个 fiber 的堆内存从 157.5 MB 降到 21.8 MB，内存密集型服务的成本模型直接改写。打包体积的缩小则来自 tree-shaking 支持——核心 effect 包官方标注支持激进摇树优化，配合 Schema 大约 15 kB。

包结构：从分散到统一

v3 时代的 Effect 生态由一组独立版本号的包组成：effect、@effect/platform、@effect/rpc、@effect/cluster、@effect/sql 各自演进，使用者需要自行核对包之间的兼容矩阵。v4 把这些全部并入核心包，改用 effect/http、effect/rpc、effect/cluster、effect/ai 这样的子路径导入。

保留独立的包只剩平台绑定、驱动和集成层：@effect/platform-*（Node、Bun、Deno、浏览器）、@effect/sql-*（各家数据库驱动）、@effect/ai-*（模型服务商）、@effect/atom-*（框架绑定）、@effect/opentelemetry 和 @effect/vitest。这些包与核心包共享同一个版本号，同步发版——装 [email protected] 就配套装 @effect/[email protected]，兼容性核对由发布流水线统一承担，使用者不再需要查表。

核心包的运行时依赖数为零。官方给出的理由直接指向供应链安全：发布的每一行代码都在自己控制范围内，不存在第三方依赖链，也就少了一条被投毒的通道。npm 上 4390 万的周下载量（2026 年 9 月 21 日当周）放大了这个决策的价值——零依赖意味着这四千多万次安装不会传递安装任何未经审计的第三方代码。

核心 API 的破坏性整理

迁移指南里最大的一处改动是服务定义方式。v3 用 Context.Tag，v4 换成 Context.Service：

// v3
class Database extends Context.Tag("Database")<Database, {
  readonly query: (sql: string) => string
}>() {}

// v4：类型参数提前，标识符后置
class Database extends Context.Service<Database, {
  readonly query: (sql: string) => string
}>()("Database") {}

同类的整理覆盖了整个核心：FiberRef 改为 Context.Reference，Cause 的嵌套结构被压平，Effect.race 系列组合子的行为语义做了修正，Runtime<R> 类型直接移除。官方生成的迁移参考文档列出了一百多个导入路径变更，其中 effect/Either 改名为 effect/Result 是命名层面最大的调整。

v4 还引入了一套显式的稳定性标签体系。effect/unstable/http 这类路径改成了 effect/http，但 API 文档用 @stability unstable 标注：带这个标签的 API 可能在 minor 版本里出现破坏性变更；@stability experimental 则可能在 patch 版本变化。没有标签的 API 遵循严格 semver。这个体系把「哪些 API 敢押上生产」写成可机读的元数据——暴露第三方依赖的 API 也被归入 unstable，因为依赖方自己的发版就可能改变它们的行为。

新能力盘点

软件事务内存（STM）进入核心：Effect.tx 提供 TxRef、TxQueue、TxHashMap、TxPubSub、TxSemaphore 等一整套事务性数据结构，并发状态的组合以事务表达，不再依赖锁的手工编排。

Schema 全面重写为 v4 实现：解析速度更快，支持类式 schema，每个 schema 自带 make 构造器，解码过程可以访问服务。SchemaRepresentation 一个入口导出 JSON Schema（Draft-04、Draft-07、2020-12）和 OpenAPI 3.0/3.1，也能生成 TypeScript 代码和 AI 结构化输出定义。SchemaBinary 提供紧凑的二进制编解码，作为集群传输的默认线上格式；JIT 和 AOT schema 编译器以实验模块提供。

HTTP 层的 HttpApi 支持带类型的响应头、流式与 SSE 响应、HTTP QUERY 方法，附带内存态测试工具 HttpApiTest，大型 API 的类型检查速度明显改善。SQL 方面，@effect/sql-pg 内置了带 pipelining 的 PostgreSQL 客户端，不再依赖 pg 包；@effect/sql-site-node 改用 Node 内置的 node:sqlite，要求 Node 22.16 以上。

AI 模块新增 EmbeddingModel、DecisionModel 分类评分 API、动态工具与工具审批机制；内置 MCP server 覆盖 2024-11-05 到 2026-07-28 的协议版本，支持 elicitation、带工具的 sampling、资源订阅和类型化工具输出。服务商包覆盖 Anthropic、OpenAI、OpenAI 兼容接口和 OpenRouter。@effect/platform-deno 补齐了完整的 Deno 支持。

LTS 政策：写进日历的承诺

Effect 4.x 的支持期从这次发布起算：bug 修复持续到 2029 年 9 月，或 5.0 发布后一年（取更晚者）；安全修复持续到 2029 年 9 月，或 5.0 发布后两年（取更晚者）。无论 5.0 何时发布，支持期至少三年。

对开源基础设施来说，这是开源基础设施补齐工程承诺的标志性动作。企业选型的常见顾虑是大版本升级没有预期——一个 effect system 深度渗透到业务代码里，破坏性升级的成本远高于换一个工具库。LTS 时间表把这笔账算清了：2029 年 9 月之前的补丁是确定的，迁移窗口是可计划的。官方同时明确，迁移指南可以直接交给编码代理处理，大部分改动能自动完成。

采用数据与生态位置

官方公布的采用曲线：周下载量 4390 万，相对 3.x 增长 179 倍；最近七天下载里 4.x（含 beta 和 RC）已占 56%，3.x 占 44%。围绕它长出了独立的社区项目，如云基础设施方向的 Alchemy 和前端方向的 Foldkit。GitHub 上主仓库约 1.69 万 star。

TypeScript 的类型系统在复杂度上早已接近静态语言的上限，但标准库对并发、资源管理、可观测性的表达一直停留在约定层面。Effect 的路径是把这些问题收进类型：类型化错误、依赖注入、结构化并发、资源生命周期都在 Effect 这一个类型的签名里。4.0 把分散的生态收拢、给出 LTS 承诺之后，「这套模型成不成立」已有采用数据作答，剩下的问题是工程团队如何低风险地迁进来。迁移指南、稳定性标签和统一版本号，都是这个问题的答卷。

工程环境要求 TypeScript 5.9 以上（官方推荐 TS 7 / tsgo 以获得最佳性能），Node.js 18 为一般下限，部分集成包要求更高。从 v3 升级走官方迁移指南，配合自动重命名映射表。

来源：

• Effect 4.0 官方发布公告
• Effect-TS/effect GitHub 仓库
• v3 → v4 迁移指南