本地开发

安装 Node.js

请先在本机安装 Node.js v22.18.0。

提示

推荐使用 nvm 或 nvm-windows 进行安装，这样便于在不同项目中切换不同的 Node.js 版本。

检查环境变量

检查项目根目录下的 .env 和其他的 .env.* 文件，确保已经配置好环境变量。尤其是数据库配置。

开启本地服务

具体命令如下：

若要使用 int 环境进行本地开发：

bash

npm run dev:int

若要使用 pre 环境进行本地开发：

bash

npm run dev:pre

若要使用 production 环境进行本地开发：

bash

npm run dev:production

开始本地开发

当你开启本地服务后，程序会自动打开系统默认浏览器访问 http://localhost:9000 网址。

说明

其实此时程序会开启多个端口，比如每个子应用对应的服务都会有一个自己的端口，但我们统一用 9000 端口代理了这些端口，这样开发者就不用考虑前后端项目端口号不一致带来的跨域问题了。

数据库迁移

生成迁移文件

bash

npx knex migrate:make temp --knexfile knexfile.mts --env production -x mts --stub node_modules/knex/lib/migrations/migrate/stub/ts.stub

运行数据库迁移

bash

cross-env MODE=int NODE_ENV=production npx knex migrate:latest --knexfile knexfile.mts --env production

回滚迁移

bash

cross-env MODE=int NODE_ENV=production npx knex migrate:rollback --knexfile knexfile.mts --env production

构建和部署

构建所有应用

bash

# 构建所有应用（以生产环境为例）
npm run build:production

# 构建特定应用（以生产环境为例）
npm run build:admin:production
npm run build:account:production
# ... 等等

# 构建并部署到生产环境
npm run buildAndDeploy:production

开发建议

1. 添加新功能

确定功能模块：确定属于哪个业务模块
设计数据库表：在 src/models/ 中创建模型定义文件
创建数据库迁移：在 migrations/ 中创建迁移文件
实现业务逻辑：在 src/services/ 中实现服务层，通常会调用 src/models/ 下定义的数据库操作方法。
创建控制器：在 src/controllers/ 中创建控制器
定义路由：在 src/routes/ 中定义路由
前端实现：在 apps/ 下对应的前端子应用里实现前端页面，在 apps-home/ 下实现需要独立域名部署的前端静态项目。
类型定义：在 typings/ 中定义相关类型

2. 代码规范

使用 TypeScript 严格模式
遵循 ESLint 规则
使用有意义的变量和函数名
添加必要的注释
保持代码简洁

3. 测试建议

数据库操作使用事务
使用 forUpdate() 锁定行，避免并发问题
金额计算使用 BigNumber，避免精度问题
验证所有用户输入

4. 性能优化

数据库查询使用索引
合理使用缓存
避免 N+1 查询问题
使用分页查询大量数据

常见问题

1. 如何添加新的前端应用？

添加 Vue3 子应用（apps 目录）

在 apps/ 目录下创建新应用目录
参考其他应用的 vite.config.mts 配置
在 package.json 中添加开发脚本
在 src/app.mts 中添加代理配置

开发脚本示例（以 your-app 为例，端口号使用 9014）：

端口号注意事项

在添加新应用时，请确保端口号不与已有应用重复。当前已使用的端口号：

apps 目录：9003-9013（admin、account、todos、bugs、design、docs、work、ppt、album、shares、health）
apps-home 目录：9099-9109（_base、blog、bugs、design、todos、ppt、systems、quilt、album、shares、health）

建议新应用使用下一个可用的端口号。

json

{
  "scripts": {
    "dev:your-app": "cross-env FOLDER_NAME=your-app PORT=9014 vite serve ./apps/your-app",
    "build:your-app": "cross-env FOLDER_NAME=your-app PORT=9014 vite build ./apps/your-app",
    "deploy:your-app": "cross-env FOLDER_NAME=your-app node build/deploy-app.mts",
    "buildAndDeploy:your-app:int": "cross-env NODE_ENV=production MODE=int node --run buildAndDeploy:your-app",
    "buildAndDeploy:your-app:pre": "cross-env NODE_ENV=production MODE=pre node --run buildAndDeploy:your-app",
    "buildAndDeploy:your-app:production": "cross-env NODE_ENV=production MODE=production node --run buildAndDeploy:your-app",
    "buildAndDeploy:your-app": "node --run build:your-app && node --run deploy:your-app",
    "lint:your-app": "vue-tsc --noEmit --project ./apps/your-app/tsconfig.json && npx prettier --write ./apps/your-app && cross-env APP_PATH_NAME=apps/your-app NODE_ENV=production MODE=production eslint -c ./eslint.config.vue.mts ./apps/your-app --fix"
  }
}

重要提示：添加完上述命令后，还需要在以下总命令中追加对应的子命令：

dev 命令：在 concurrently 中添加 \"node --run dev:your-app\"

json

"dev": "node --run clean:files && concurrently -n \"front,server,admin,account,todos,work,ppt,bugs,design,docs,consumers,album,shares,health,your-app\" \"node --run dev:front\" \"node --run dev:server\" ... \"node --run dev:your-app\""

build 命令：追加 node --run build:your-app

json

"build": "node --run clean:files && node --run build:front && node --run build:admin && ... && node --run build:your-app"

deploy 命令：追加 node --run deploy:your-app

json

"deploy": "node --run deploy:front && node --run deploy:admin && ... && node --run deploy:your-app && node --run deploy:server"

lint 命令：追加 node --run lint:your-app

json

"lint": "node --run lint:front && node --run lint:nginx && node --run lint:server && ... && node --run lint:your-app"

添加 Nuxt 4 独立项目（apps-home 目录）

复制 apps-home/_base 目录到 apps-home/your-project-name
修改 nuxt.config.ts 中的 cdnURL 配置（CDN 地址）
修改 build/deploy.mts 中的 domain 配置（部署域名）
在 app/pages/ 目录下创建页面文件（基于文件系统的路由）
在 package.json 中添加开发脚本（需要设置 FOLDER_NAME 和 PORT 环境变量）
在 src/app.mts 中添加代理配置（如果需要）

开发脚本示例（以 your-project 为例，端口号使用 9110）：

端口号注意事项

在添加新项目时，请确保端口号不与已有项目重复。当前已使用的端口号：

apps 目录：9003-9013
apps-home 目录：9099-9109

建议新项目使用下一个可用的端口号（如 9110）。

json

{
  "scripts": {
    "home:your-project:dev": "cross-env FOLDER_NAME=your-project NODE_ENV=development MODE=production PORT=9110 nuxt dev --cwd=./apps-home/your-project",
    "home:your-project:lint": "npx prettier --write ./apps-home/your-project && cross-env APP_PATH_NAME=apps-home/your-project NODE_ENV=production MODE=production eslint -c ./eslint.config.vue.mts ./apps-home/your-project --fix && cross-env FOLDER_NAME=your-project NODE_ENV=production MODE=production PORT=9110 nuxt typecheck --cwd=./apps-home/your-project",
    "home:your-project:build": "cross-env FOLDER_NAME=your-project NODE_ENV=production MODE=production PORT=9110 nuxt generate --cwd=./apps-home/your-project",
    "home:your-project:buildAndDeploy": "node --run home:your-project:build && cross-env NODE_ENV=production MODE=production FOLDER_NAME=your-project node ./apps-home/your-project/build/deploy.mts"
  }
}

注意事项：

Vue3 子应用（apps 目录）：
- 使用 vite serve 进行开发，使用 vite build 进行构建
- 需要设置 FOLDER_NAME 和 PORT 环境变量
- 部署时使用 build/deploy-app.mts 脚本
Nuxt 4 独立项目（apps-home 目录）：
- 使用 nuxt dev 进行开发，使用 nuxt generate 进行构建
- 需要设置 FOLDER_NAME、NODE_ENV、MODE 和 PORT 环境变量
- 使用 --cwd 参数指定项目目录
- Nuxt 4 项目使用基于文件系统的路由，在 app/pages/ 目录下创建 .vue 文件即可自动生成路由
- 动态路由使用 [param].vue 或 [...slug].vue 命名
- 编译产物会输出到 node_modules/.nuxt-{FOLDER_NAME}/.output/public 目录
- 部署时使用项目目录下的 build/deploy.mts 脚本，会自动将 .html 文件上传到服务器，其他静态资源上传到 CDN

2. 如何添加新的数据库表？

在 src/models/ 中创建模型文件
在 src/models/index.mts 中注册表创建函数
在 typings/ 中创建类型定义文件（如 table-name.d.ts）
在 typings/knex.d.ts 中添加表类型映射：
- 添加基础类型：table_name: TableType
- 如果表有 id 和 created_at/updated_at 字段，添加复合类型：table_name_composite: CompositeTableType<TableType>
- 确保表名与模型文件中的 tableName 完全一致
在 migrations/ 中创建迁移文件（如果需要）
运行迁移：npx knex migrate:latest

注意：删除表时，需要同步从 typings/knex.d.ts 中移除表定义，并删除对应的类型定义文件。

3. 如何添加新的 API 接口？

在 src/services/ 中实现业务逻辑
在 src/controllers/ 中创建控制器
在 src/routes/ 中定义路由
在 src/routes/index.mts 中注册路由

4. 如何配置环境变量？

在 .env 或 .env.int、.env.pre、.env.production 中定义变量（如果是通用的变量就定义到 .env 中，否则定义到具体的环境对应的文件中）。
在 src/scripts/ConstantUtils.mts 中添加常量定义
在代码中使用该常量

本地开发

相关文档

快速参考

技术规范

部署相关

安装 Node.js

检查环境变量

开启本地服务

开始本地开发

数据库迁移

生成迁移文件

运行数据库迁移

回滚迁移

构建和部署

构建所有应用

开发建议

1. 添加新功能

2. 代码规范

3. 测试建议

4. 性能优化

常见问题

1. 如何添加新的前端应用？

添加 Vue3 子应用（apps 目录）

添加 Nuxt 4 独立项目（apps-home 目录）

2. 如何添加新的数据库表？

3. 如何添加新的 API 接口？

4. 如何配置环境变量？

本地开发 ​

相关文档 ​

快速参考 ​

技术规范 ​

部署相关 ​

安装 Node.js ​

检查环境变量 ​

开启本地服务 ​

开始本地开发 ​

数据库迁移 ​

生成迁移文件 ​

运行数据库迁移 ​

回滚迁移 ​

构建和部署 ​

构建所有应用 ​

开发建议 ​

1. 添加新功能 ​

2. 代码规范 ​

3. 测试建议 ​

4. 性能优化 ​

常见问题 ​

1. 如何添加新的前端应用？ ​

添加 Vue3 子应用（apps 目录） ​

添加 Nuxt 4 独立项目（apps-home 目录） ​

2. 如何添加新的数据库表？ ​

3. 如何添加新的 API 接口？ ​

4. 如何配置环境变量？ ​

本地开发

相关文档

快速参考

技术规范

部署相关

安装 Node.js

检查环境变量

开启本地服务

开始本地开发

数据库迁移

生成迁移文件

运行数据库迁移

回滚迁移

构建和部署

构建所有应用

开发建议

1. 添加新功能

2. 代码规范

3. 测试建议

4. 性能优化

常见问题

1. 如何添加新的前端应用？

添加 Vue3 子应用（apps 目录）

添加 Nuxt 4 独立项目（apps-home 目录）

2. 如何添加新的数据库表？

3. 如何添加新的 API 接口？

4. 如何配置环境变量？