Nx Monorepo 架构：18+ 个包的依赖管理与构建策略

Nx Monorepo 架构：18+ 个包的依赖管理与构建策略

学习目标

理解 CopilotKit 的 Nx Monorepo 组织：

• 扁平包结构与依赖关系
• 构建管道与任务编排
• 测试策略与 E2E 集成测试
• 发布策略（Changesets）

前置知识

无特定前置知识。

项目实践

包结构

所有包位于 packages/ 目录下，使用 @copilotkit/ scope：

包名	职责	依赖
@copilotkit/shared	公共工具、类型、常量	无内部依赖
@copilotkit/core	CopilotKitCore 核心	shared, @ag-ui/client
@copilotkit/react-core	React 绑定	core, shared, runtime-client-gql
@copilotkit/react-ui	Chat UI 组件	react-core, shared
@copilotkit/react-textarea	AI 辅助文本编辑	react-core, shared
@copilotkit/react-native	React Native 绑定	react-core, shared
@copilotkit/angular	Angular 绑定	core, shared
@copilotkit/vue	Vue 绑定	core, shared
@copilotkit/runtime	服务器运行时	shared, @ag-ui/*, LLM SDKs
@copilotkit/runtime-client-gql	GraphQL 客户端	shared, @ag-ui/client
@copilotkit/sdk-js	LangGraph/LangChain 集成辅助	shared
@copilotkit/voice	语音输入	shared
@copilotkit/web-inspector	调试控制台（Lit 组件）	—
@copilotkit/sqlite-runner	SQLite 持久化 Runner	runtime
@copilotkit/agentcore-runner	AgentCore Runner	runtime
@copilotkit/demo-agents	示例 Agent	runtime
@copilotkit/a2ui-renderer	A2UI 渲染器	shared

依赖关系图

构建工具链

工具	用途	配置
Nx	任务编排、影响分析、项目图	nx.json
pnpm	包管理器、workspace 管理	pnpm-workspace.yaml
tsdown	TypeScript 打包	各包 tsdown.config.ts
Vitest	单元测试	各包 vitest.config.mjs
oxlint	Lint	.oxlintrc.json
oxfmt	格式化	.oxfmtrc.json
commitlint	提交信息规范	commitlint.config.js
lefthook	Git 钩子	lefthook.yml

Nx 任务

# 构建所有包
pnpm run build          # nx run-many -t build --projects=packages/**

# 测试所有包
pnpm run test           # nx run-many -t test --projects=packages/**

# 仅测试受影响的包
nx affected -t test

# 开发模式（watch 变更自动重新构建）
pnpm run dev

# 发布包验证
pnpm run check:packages  # publint + attw

依赖图可视化

nx graph    # 在浏览器中查看项目依赖图

E2E 集成测试

packages/runtime/src/v2/runtime/__tests__/integration/ 目录包含多种服务器集成测试：

服务器	文件
Express 单端点	servers/express-single.ts
Express 多端点	servers/express-multi.ts
Hono 单端点	servers/hono-single.ts
Hono 多端点	servers/hono-multi.ts
Node Fetch Handler	servers/node-multi.ts
Bun + Elysia	bun/elysia-single.ts, bun/hono-bun-multi.ts

测试套件（suites/ 目录）：

• single-endpoint.suite.ts：单端点传输的通用测试
• multi-endpoint.suite.ts：多端点传输的通用测试
• debug-events.suite.ts：调试事件测试

同一套测试用例在不同服务器上复用，确保行为一致性。

发布策略

Changesets 管理版本：

# 准备发布（dry run）
pnpm run release:prepare:dry

# 预发布（dry run）
pnpm run release:prerelease:dry

所有包共享版本号（如 1.8.2），但每个包有独立的 CHANGELOG.md。

问题与规避

问题	规避策略
包版本不匹配导致类型错误	统一版本号策略；所有包同时发布
循环依赖	扁平结构降低风险；nx graph 可视化检测循环
构建顺序错误	Nx 自动推导依赖图，确保按正确顺序构建
pnpm 与 nx 项目图不同步	.nx 缓存目录管理；nx reset 清理状态

设计取舍

Nx vs Turborepo

Nx 优势：

• 内置项目图可视化（nx graph）
• affected 命令精确计算受影响的包
• 丰富的插件生态

Turborepo 优势：

• 配置更简单（单个 turbo.json）
• 与 Vercel 生态集成更深

flat vs nested 包结构

扁平结构（CopilotKit 的选择）：

• 优势：依赖关系一目了然，降低嵌套混淆
• 代价：所有包在同一层级，没有子目录分组

嵌套结构：

• 优势：可按功能分组（如 packages/adapters/、packages/clients/）
• 代价：路径变长，依赖关系不够直观

参考来源

• nx.json
• pnpm-workspace.yaml
• package.json（scripts 部分）
• packages/*/package.json（依赖声明）