Effect TS 类型提示在 VSCode 中不生效的根本原因是 tsconfig.json 未启用 strict 模式或未正确配置 typeRoots、types 等选项，导致 TypeScript 无法加载 Effect 的高级类型定义，进而使泛型推导失效、符号不可见、补全丢失。
Effect TS 的类型提示为什么在 VSCode 里不生效
根本原因通常是 tsconfig.json 没正确启用 strict 模式或没识别到 Effect 的类型定义。Effect（尤其是 v3+）重度依赖 TypeScript 的高级类型推导能力，比如 effect、pipe、match 这些函数的返回类型会随参数变化动态推导——一旦 TS 配置宽松，类型就“塌缩”成 any 或 unknown，VSCode 自然没法给出精准提示。
常见错误现象：
– 输入 Effect.succeed(42).map 后没自动补全
– pipe(eff, Effect.map(...)) 中鼠标悬停显示 (method) map<...>(...): any
– Effect.runPromise 调用时报红，但实际能运行
- 确保项目根目录有
tsconfig.json，且包含"strict": true（不是只开"strictNullChecks"） - Effect v3 要求 TypeScript ≥ 5.0，检查
node_modules/typescript版本，别用全局 TS - 如果用了 pnpm/yarn，确认
@effect/io和@effect/ts已安装，且没有被package.json#resolutions错误覆盖版本
VSCode 无法识别 Effect 的全局类型声明（如 Effect、Option）
Effect 的类型不是靠全局 declare global 注入的，而是通过模块路径导入触发类型加载。VSCode 默认不会主动扫描 node_modules/@effect/* 下的 index.d.ts，尤其当项目没显式 import 过 Effect 模块时，符号就不可见。
使用场景：新建文件写 const x = Effect.succeed("ok")，VSCode 报错 Cannot find name 'Effect'
- 在任意 TS 文件顶部加一行
import * as Effect from "@effect/io"（哪怕后续删掉），能强制 TS 服务加载 Effect 类型 - 更稳妥的做法是在
tsconfig.json的"types"字段中显式声明："types": ["@effect/io", "@effect/data"] - 避免用
/// <reference types="@effect/io" />—— VSCode 对三斜线引用支持不稳定，尤其在 monorepo 中容易失效
pipe 和 match 的链式推导总出错或中断
Effect 的 pipe 是类型安全的关键，但它对泛型链的推导极其敏感。VSCode 的 TS 语言服务在处理长链（尤其是嵌套 pipe 或混用 Effect/Option/Either）时，容易因缓存或超时放弃推导，表现为中间步骤类型变 any，后续方法补全消失。
性能影响：每多一层 pipe 调用，TS 编译器需重新计算联合/交叉类型，v3 的新类型系统对此更重
- 把过长的
pipe拆成带明确类型的中间变量，例如：const parsed = pipe(input, Effect.parseJson);而不是直接pipe(input, Effect.parseJson, Effect.map(...)) - 给
match的每个分支标注返回类型，特别是onError和onSuccess，否则 TS 可能推导出宽泛的联合类型 - 禁用 VSCode 的 “TypeScript: Use Workspace Version”（设置里搜），改用项目本地
node_modules/typescript，避免版本错配导致推导降级
Effect 错误检查不准，比如 Effect.fail 不报红但运行时崩溃
Effect 的错误路径（Effect.fail、Effect.die）是否被检查，取决于你是否启用了 "noUncheckedIndexedAccess" 和 "exactOptionalPropertyTypes"，以及是否在 tsconfig.json 中配置了 "typeRoots" 指向 Effect 的类型包。
容易踩的坑：
– Effect.fail(new Error("x")) 看似没问题，但如果你的函数签名声明返回 Effect.Effect<string>，而没声明错误类型（即漏了 never 或具体错误类型），TS 就不会校验失败路径
– Effect.tryPromise 的 reject 类型默认是 unknown，不加 as const 或类型断言，错误检查形同虚设
- 所有 Effect 函数调用，尽量显式标注完整泛型：例如
Effect.fail<MyError>(new MyError())，而不是依赖推导 - 在
tsconfig.json中添加"typeRoots": ["./node_modules/@effect/io/_mjs"]（注意路径后缀，Effect v3+ 用_mjs目录提供 ESM 类型） - 别依赖 VSCode 的“快速修复”自动补全类型——它常把
Effect.Effect<A, E, R>简化为Effect.Effect<A>，丢掉E和R，导致错误检查失效
Effect 的类型系统不是“开箱即用”的友好型，它把控制权交给了开发者：你声明得越精确，VSCode 提示就越准；省略泛型、关 strict、混用模块解析方式，都会让类型检查迅速退化。最常被忽略的是 typeRoots 路径和 _mjs 目录的存在——没配对，连基础符号都找不到。
