如何快速搭建 effect-smol 开发环境：pnpm monorepo 完整配置指南
【免费下载链接】effect-smolCore libraries and experimental work for Effect v4项目地址: https://gitcode.com/GitHub_Trending/ef/effect-smol
effect-smol是 Effect 团队实验 Effect v4 核心库的 monorepo 仓库，包含effect核心包、平台适配、AI、SQL、原子化状态等 30 多个子包。本文是一份面向新手的pnpm monorepo 配置教程，带你从安装依赖到跑通测试，用 5 步完成effect-smol 开发环境搭建。
⚠️ 小提示：该仓库目前已归档为只读状态（见 README.md），但仓库内的工程结构对理解大型 pnpm monorepo 极具参考价值。
一、环境准备：确认 Node.js 与 pnpm 版本
在开始pnpm monorepo 配置之前，先确认两个前置条件：
| 工具 | 版本要求 | 说明 |
|---|---|---|
| Node.js | 24+（推荐 26） | 本地可直接运行.ts文件，无需 tsx |
| pnpm | 10.17.1 | 由packageManager字段锁定 |
仓库根目录的 package.json 中通过packageManager字段声明了 pnpm 版本：
"packageManager": "pnpm@10.17.1"开启 Corepack 后，pnpm 会自动对齐到该版本：
corepack enable💡 仓库还附带了 Nix 配置 flake.nix，提供包含bun、deno、nodejs_26、corepack的开发者 shell，追求环境可复现的同学可以试试。
二、一键安装：克隆仓库并拉取依赖
使用 git 克隆仓库（仅此处提供仓库地址）：
git clone https://gitcode.com/GitHub_Trending/ef/effect-smol cd effect-smol pnpm install安装过程会处理两类特殊配置，均来自根 package.json：
- 依赖补丁：
patches/目录下对@changesets/assemble-release-plan和@changesets/get-github-info的本地补丁会被自动应用； - 构建白名单：
onlyBuiltDependencies只允许better-sqlite3执行原生构建脚本，其余原生依赖（esbuild、sharp 等）被忽略，安装因此又快又安全。
三、看懂结构：pnpm workspace 工作区划分
工作区定义在 pnpm-workspace.yaml，一眼就能看懂这个pnpm monorepo的组织方式：
packages: - ai-docs # AI 文档示例 - scratchpad # 本地试验场 - scripts # 工程脚本 - packages/* # 核心包 - packages/ai/* # AI 相关（openai / anthropic 等） - packages/atom/* # React / Solid / Vue 响应式绑定 - packages/sql/* # 各数据库驱动 - packages/tools/*# 代码生成与打包工具各目录职责速览：
- 📦核心库：packages/effect/src/ 是 v4 主干（当前版本 4.0.0-beta.98），包含 Effect、Stream、Schema 等模块；
- 🌐平台适配：
packages/platform-node、packages/platform-browser、packages/platform-bun提供不同运行时能力； - 🧪试验场：scratchpad/ 预置了全部 workspace 包依赖，是随手写代码的最佳位置；
- 🔧工程化：scripts/ 下是 codemod、清理、文档生成等脚本。
TypeScript 编译由 tsconfig.base.json 统一约束：composite项目引用 + 增量编译，目标是 ES2022、NodeNext模块，并启用了strict全家桶。
四、日常开发：5 条最常用的 pnpm 命令
以下命令均定义在根 package.json 的scripts中：
| 命令 | 作用 |
|---|---|
pnpm test | 启动 Vitest，支持传入文件做定向测试 |
pnpm check | 全仓库 TypeScript 类型检查（tsc -b） |
pnpm lint/pnpm lint-fix | JSDoc 校验 + oxlint 静态检查 + dprint 格式化 |
pnpm codegen | 重新生成各包index.tsbarrel 文件（增删模块后必跑） |
pnpm build | 编译所有包并构建产物 |
测试体系基于 Vitest 项目分组，入口是根 vitest.config.ts：它会自动收集packages/*下每个子包的vitest.config.ts，并根据当前运行时（Deno / Bun）自动排除不兼容的包，无需手动指定。
测试规范可参考 AGENTS.md：测试文件放在packages/*/test/，类型级测试放在packages/*/typetest/并用pnpm test-types <filename>运行。
五、快速验证：在 scratchpad 里跑一段代码
环境是否搭好，跑通一次才算数。在 scratchpad/ 中新建一个文件，用 Node 24 直接运行（无需编译）：
node scratchpad/index.tsAGENTS.md 中的建议正是如此：随手验证代码就丢进 scratchpad，跑完再删除，保持仓库整洁。
六、进阶可选：一键启动数据库测试环境
如果你要跑 SQL 或 Cluster 相关测试，仓库提供了 docker-compose.yaml，一键拉起本地 Postgres 与 Redis：
docker compose up -d- Postgres：
5432端口，库名effect_cluster； - Redis：
6379端口。
七、常见问题 FAQ
Q1：pnpm install报错版本不匹配？先执行corepack enable再corepack prepare，让 pnpm 对齐packageManager锁定版本。
Q2：为什么index.ts内容看起来是自动生成的？barrel 文件由 codegen 生成，禁止手改——增删模块后运行pnpm codegen即可（规则见 AGENTS.md）。
Q3：改动后应该跑哪些校验？按最小覆盖原则：改代码 →pnpm lint-fix+ 定向pnpm test <文件>+pnpm check；改 JSDoc →pnpm lint。完整对照表见 AGENTS.md。
总结
effect-smol 开发环境搭建的关键就三步：
- ✅ Corepack 启用 pnpm 10，克隆仓库执行
pnpm install； - ✅ 读懂 pnpm-workspace.yaml 的工作区划分，找到你要改的包；
- ✅ 用
pnpm test/pnpm check/pnpm lint完成日常校验。
掌握这套pnpm monorepo 完整配置流程后，你可以把同样的模式迁移到任何大型多包 TypeScript 项目中。
【免费下载链接】effect-smolCore libraries and experimental work for Effect v4项目地址: https://gitcode.com/GitHub_Trending/ef/effect-smol
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
