开发者工具

配置 Effect Language Service、Oxlint 与编辑器扩展，获得实时诊断、智能补全与重构。

Effect 提供了一系列强大的开发工具，用来提升你的编码体验，帮助你编写更安全、更易维护的代码。这些工具会直接集成到你的编辑器中，为你和你的 agent 提供实时反馈、智能重构以及有用的诊断信息。

Effect LSP (`@effect/tsgo`)

Effect Language Service 用 Effect 专属功能扩展了你的编辑器。它会分析你的 Effect 代码，并通过诊断、快速信息、代码补全和自动重构来提供智能辅助。

该语言服务以 @effect/tsgo 的形式发布：它是 TypeScript-Go（新的基于 Go 的 TypeScript 编译器）的一个构建版本，并内置了 Effect 诊断层。@effect/tsgo 以 CLI 的形式运行，用于完成这个修改版 TypeScript-Go 的安装。

它可以在支持标准 TypeScript LSP 的编辑器中工作，例如 Code、Cursor、Zed、NVim 等。

安装

在你的项目中设置 @effect/tsgo 最快的方式是使用交互式 CLI：

npx @effect/tsgo setup

它会引导你添加依赖、配置 tsconfig.json、调整插件选项，以及完成激活 LSP 所需的任何编辑器配置。

你也可以让 LLM agent 直接执行安装，只需把它指向 CLI 的设置与安装 readme：

Install and enable https://github.com/Effect-TS/tsgo in this project using npx @effect/tsgo setup --help

如果你想改为手动设置：

将包安装为开发依赖：

对于 monorepo，我们建议在根目录层级安装。对于单包项目，请在包目录中安装。
npm
```
npm install @effect/tsgo --save-dev
```
pnpm
```
pnpm add -D @effect/tsgo
```
Yarn
```
yarn add --dev @effect/tsgo
```
Bun
```
bun add --dev @effect/tsgo
```
@effect/tsgo 还需要安装原生 TypeScript 7：typescript 版本 7 或更高，例如 typescript@latest 或 typescript@next，或者使用像 @typescript/native 这样的别名。

将插件添加到你的 tsconfig.json（尽管包名是 @effect/tsgo，插件的 name 仍然保持为 @effect/language-service）：

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@effect/language-service"
      }
    ]
  }
}

将以下脚本添加到你的 package.json，以确保在重启后安装的是修改后的 TypeScript 版本：
```
{
  "scripts": {
    "prepare": "effect-tsgo patch"
  }
}
```
然后运行你的包管理器的安装命令
npm
```
npm install
```
pnpm
```
pnpm install
```
Yarn
```
yarn install
```
Bun
```
bun install
```
确保你的编辑器使用工作区中的 TypeScript 版本：

这一步对语言服务能否正常工作至关重要。插件必须运行在你项目所安装的 TypeScript 版本上，而不是编辑器内置的版本。

提示

在 VS Code 或 Cursor 中，你可以打开一个 TypeScript 文件，点击状态栏中的 TypeScript 版本号，然后选择 “Use Workspace Version”，即可选用工作区的 TypeScript 版本。
现在你可以开始上手了！

在你的项目中新建一个 file.ts 并写入以下代码，应该会出现一条错误诊断，提示 Effect 必须被 yield 或赋值给变量：
```
import { Effect } from "effect"

Effect.log("Hello world!")
// ^- should be run or assigned to a variable!
```

功能特性

Effect Language Service 提供了一整套完善的功能，用来提升你的开发工作流：

智能快速信息

将鼠标悬停在 Effect 值上，即可查看扩展的类型信息和详细的洞察：

Effect 类型：查看 Effect 值的完整类型信息
Generator 参数：在 Effect.gen 中悬停在 yield* 上时，查看所 yield 值的详细信息
Layer 组合：借助交互式图表可视化 Layer 依赖，展示各个 Layer 是如何组合在一起的
Service 依赖：一眼看清服务的需求以及它们之间的依赖关系

实时诊断

在编写代码时及时发现常见错误和潜在问题：

游离的 Effect：检测未被赋值或未 yield 的 Effect 值，避免出现静默 bug
Layer 问题：在运行前捕获 Layer 需求泄漏和作用域违规
不必要的代码：识别多余的 Effect.gen 或 pipe() 调用
错误处理：检测在不会失败的 Effect 上误用 catch 函数的情况
版本冲突：检测项目中是否存在多个 Effect 版本

智能补全

借助上下文感知的建议加快编码速度：

Generator 样板代码：快速生成 Effect.gen 函数骨架
脚手架：用于 Context.Service、Data.TaggedError 以及类似结构。
Self 参数：为服务声明中的 Self 参数提供自动补全

强大的重构

通过智能自动重构来改造你的代码：

Async 转 Effect：使用 gen 或 fn 语法将 async 函数转换为 Effect
错误生成：从基于 Promise 的代码生成 tagged error
Service 访问器：自动实现服务访问器函数
Pipe 转换：将函数调用转换为 pipe 语法
Pipe 风格：在不同的 pipe 风格格式之间切换
Layer 魔法：自动按正确的依赖关系组合 Layer

配置

Effect LSP 还提供了大量配置选项，例如修改严重级别或禁用某些诊断消息。

要查看完整的选项与功能列表，请访问 tsgo 仓库的 README。

构建时诊断

LSP 只在编辑会话期间生效，而你可能希望在构建过程中也能捕获诊断信息。

安装 @effect/tsgo 后，Effect 诊断会被当作普通的 TypeScript 诊断来处理，因此你的 LLM agent 可以轻松访问和读取它们。

Oxlint

请确保同时安装了 Oxlint 和 Effect TypeScript-Go 集成。以下命令会安装两者的最新版本：

npm

npm install @effect/tsgo oxlint oxlint-tsgolint --save-dev

pnpm

pnpm add -D @effect/tsgo oxlint oxlint-tsgolint

Yarn

yarn add --dev @effect/tsgo oxlint oxlint-tsgolint

Bun

bun add --dev @effect/tsgo oxlint oxlint-tsgolint

更新 package.json 的 scripts 部分，加入以下内容：

{
  "scripts": {
    "prepare": "effect-tsgo patch --oxlint"
  }
}

这样在每次安装依赖后，都会为 Oxlint 打补丁，使其使用 Effect TypeScript-Go 集成。如果不想修改 TypeScript，可以使用 --no-typescript 标志：effect-tsgo patch --no-typescript --oxlint。这样只会为 Oxlint 打补丁以使用 Effect TypeScript-Go 集成，而不会修改 TypeScript。

如果你同时启用了 Effect LSP，我们建议在 LSP 插件设置中将 diagnostics 设为 false，这样 Effect 诊断只会由 Oxlint 报告，不会重复出现：

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@effect/language-service",
        "diagnostics": false
      }
    ]
  }
}

运行你的包管理器的安装命令来安装依赖，并执行用于为 Oxlint 打补丁的 prepare 脚本。

npm

npm install

pnpm

pnpm install

Yarn

yarn install

Bun

bun install

Effect 规则需要 Oxlint 的类型感知模式以及 effecttsgo 插件。推荐的 preset 会同时启用这两者，并配置推荐的 Effect 规则。使用 @effect/tsgo 附带的 schema 来获得校验和补全：

{
  "$schema": "./node_modules/@effect/tsgo/oxlint-schema.json",
  "extends": ["./node_modules/@effect/tsgo/oxlint-presets/recommended.json"]
}

也可以通过 .ts 形式的 Oxlint/Vite Plus 配置文件启用规则，preset 可以通过以下方式获取：

import { recommended } from "@effect/tsgo/oxlint-presets"
import { defineConfig } from "oxlint"

export default defineConfig({
  extends: [recommended],
})

Vite Plus

Vite Plus 在内部自带了一份捆绑的 Oxlint 和 Oxlint-TSGoLint。

请确保已安装 Effect TypeScript-Go 集成：

npm

npm install @effect/tsgo --save-dev

pnpm

pnpm add -D @effect/tsgo

Yarn

yarn add --dev @effect/tsgo

Bun

bun add --dev @effect/tsgo

更新 package.json 的 scripts 部分，加入以下内容：

{
  "scripts": {
    "prepare": "effect-tsgo patch --oxlint"
  }
}

这样在每次安装依赖后，都会为 Vite Plus 捆绑的 Oxlint 打补丁，使其使用 Effect TypeScript-Go 集成。如果不想修改 TypeScript，可以使用 --no-typescript 标志：effect-tsgo patch --no-typescript --oxlint。这样只会为 Vite Plus 的 Oxlint 打补丁以使用 Effect TypeScript-Go 集成，而不会修改 TypeScript。

如果你同时启用了 Effect LSP，我们建议在 LSP 插件设置中将 diagnostics 设为 false，这样 Effect 诊断只会由 Vite Plus 的 Oxlint 报告，不会重复出现：

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@effect/language-service",
        "diagnostics": false
      }
    ]
  }
}

运行你的包管理器的安装命令来安装依赖，并执行用于为 Oxlint 打补丁的 prepare 脚本。

npm

npm install

pnpm

pnpm install

Yarn

yarn install

Bun

bun install

现在你可以在 Vite Plus 配置文件中启用 Effect 规则，例如通过 extends 推荐的 preset：

import { defineConfig } from "vite-plus"
import { recommended } from "@effect/tsgo/oxlint-presets" // <- add import to recommended settings

export default defineConfig({
  lint: {
    extends: [recommended], // <- add extends recommended ones
    // ...
  },
  // ...
})

VS Code / Cursor 扩展

注意

编辑器扩展并不包含 Effect LSP！ Effect LSP 的安装应当按项目分别进行，这样可以精细地控制何时加载它、为哪些项目加载，以及使用由仓库 lockfile 固定下来的版本。

编辑器扩展提供了一些实用工具，帮助你调试 Effect 应用。

目前只支持 Code 以及像 Cursor 这样的 Code 分支。

安装

你可以在编辑器的扩展页面中直接搜索安装该扩展，也可以从 Code Marketplace 或 Open VSX Marketplace 安装。

调试器功能

使用 Effect 扩展后，你会在编辑器的 Debug 区域中看到几个新的小节，当你暂停执行时，它们会显示相关信息。

Context：允许你查看当前暂停的 Effect Fiber 的上下文。
Span Stack：显示引导你进入当前暂停的 Effect 执行的遥测 span 堆栈。
Fibers：列出应用中正在运行的所有 Effect Fiber，允许你查看诸如可中断性等信息，并允许请求中断它们。
Breakpoints：启用 “pause on defect”，让调试器在某个 Effect fiber 因 defect 而失败时暂停。

Effect LSP (@effect/tsgo)

安装

功能特性

智能快速信息

实时诊断

智能补全

强大的重构

配置

构建时诊断

Oxlint

Vite Plus

VS Code / Cursor 扩展

安装

调试器功能

Effect LSP (`@effect/tsgo`)