用途
本指南面向使用 Convex 构建后端的开发者，讲解如何通过 Convex Components 对功能进行封装，从而获得可维护、可复用的后端结构。
什么是 Convex Components
组件是自包含的迷你后端，自带数据库 schema、查询/变更/动作函数、隔离的数据表以及清晰的 API 边界。资料将其类比为「后端的 npm 包」或「无需承担部署复杂度的微服务」。
主要能力与用法
- 安装与配置：通过 npm 安装官方组件（如
npm install @convex-dev/ratelimiter），在convex.config.ts中使用defineApp注册组件，然后在业务代码中通过components调用。 - 兄弟组件模式：多个组件在同一层级各负责单一关注点（认证、存储、支付、邮件、分析等），由主应用编排调用。示例展示了订阅流程中依次调用认证、支付、分析、邮件组件并写入主应用表。
- 官方组件目录：包括认证（@convex-dev/better-auth）、存储（@convex-dev/r2、@convex-dev/storage）、支付（@convex-dev/polar）、AI（@convex-dev/agent、@convex-dev/embeddings）、后端工具（ratelimiter、aggregate、action-cache、sharded-counter、migrations、workflow）等。
- 自定义组件：给出创建步骤与目录结构示例（
convex.config.ts、schema.ts、函数文件），并说明适合创建组件的场景（自包含功能、跨项目复用、复杂数据模型、第三方集成封装）与不适合的场景（一次性业务逻辑、与主应用紧耦合、简单工具函数）。 - 组件通信规则：父级调用组件、父级编排多个兄弟组件、向组件传入父级表 ID 均属推荐做法；组件不能直接访问父级表，兄弟组件之间也不能互相调用。
- 架构示例：列出多租户 SaaS、电商平台、AI 应用三类组合方式，并给出从单体代码逐步抽取组件的迁移步骤。
- 最佳实践：单一职责、清晰的 API 表面、最小耦合、版本管理与文档编写，以及常见问题排查（组件未找到、无法访问父表、组件冲突）。
适用场景
需要将文件存储、认证、计费、邮件、分析、限流等通用能力从业务代码中解耦，或希望跨项目复用后端功能、独立测试与更新组件的 Convex 项目。
限制
组件被沙箱隔离，无法访问父应用数据表，组件之间也不能直接通信，协作需由主应用编排；资料未说明收费、价格或性能指标。