开发指南
本章面向在 Nexus 基础上做二次开发的工程师。Nexus 的开发就是标准 Nuxt 4 开发，但扩展业务优先以模块形式落地，以保持与主应用、框架上游的解耦。
环境配置
- 详见 快速开始：
npm install→cp .env.example .env→ 准备 PostgreSQL →npx drizzle-kit migrate→npm run dev。 - 环境变量完整说明见 环境变量。
代码规范
新增功能模块
推荐用模块机制扩展，而非直接堆在主应用：
- 在
modules/<your-module>/下创建nexus-module.json（声明pages/api/migrations/menu出口）。 - 添加对应的
pages/、api/、migrations/、menu.json。 - 在
config/modules.ts把模块名加入enabledModules。 - 重启开发服务器，页面/API/菜单/迁移自动生效。
详见 模块机制。
新增页面 / API（轻量场景）
- 页面：在
app/pages/下按约定新建.vue（kebab-case），Nuxt 自动生成路由。 - API 路由：在
server/api/下新建<resource>.<method>.ts，文件名即路由（users.get.ts→GET /api/users）。 - 数据库表：在
server/database/schema.ts增表定义，并npx drizzle-kit generate+migrate生成并执行迁移。
测试
package.json 的 test 脚本包含两部分：
- 结构测试（
tests/structure/）：校验页面、路由、布局、数据层、模块系统等是否符合约定（如公共页、admin 控制台、模块系统、AI 适配器、支付集成等）。 - 单元测试（
tests/unit/）：Vitest 运行。
| 命令 | 说明 |
|---|---|
npm test | 全量测试（结构 + 单元） |
npm run test:watch | 单元测试监听模式 |
npm run test:structure | 仅结构测试 |
结构测试是 Nexus 的「架构护栏」：新增页面/模块时，若不符合命名与目录约定，测试会失败，防止架构漂移。
调试技巧
- 服务端日志：
npm run dev终端直接输出 API 请求、迁移、邮件（未配 SMTP 时）等日志。 - API 文档：
/api_docs（Scalar）可交互调试接口；/api/docs/openapi.json为 OpenAPI 定义。 - 数据库：用
psql/ 任意 PostgreSQL 客户端连接NUXT_DATABASE_URL查看表结构与数据。 - 模块加载：若模块页面/菜单未出现，检查
config/modules.ts是否启用、模块目录结构是否符合nexus-module.json声明的 exports。
AI 协作开发
Nexus 原生面向 Coding Agent。推荐用 AI 驱动开发 的规格驱动方式扩展项目，让 Agent 在可读规则与可追溯规格下安全实施。