mini-starter/docs/guides/local-development.md

本地开发指南

开发工作流

日常开发流程

1. 拉取最新代码

   git pull origin monorepo
   pnpm install
   

2. 创建功能分支

   git checkout -b feature/your-feature-name
   

3. 启动开发环境

   # 构建共享包（如果修改了共享代码）
   pnpm run build:mini-ui-packages
   
   # 启动应用
   pnpm dev
   

4. 开发和测试

   • 在浏览器中访问 http://localhost:8080
   • 进行功能开发和调试

5. 代码检查

   # 类型检查
   pnpm typecheck
   
   # 代码检查
   pnpm lint
   
   # 运行测试
   pnpm test
   

6. 提交代码

   git add .
   git commit -m "feat: 描述你的功能"
   git push origin feature/your-feature-name
   

包开发

开发共享包

共享包（如 shared-utils, shared-types）在开发时需要启用监听模式：

cd packages/shared-utils
pnpm dev  # 启动 TypeScript 监听模式

开发业务模块

后端模块开发

cd allin-packages/channel-module

# 编辑代码
# src/entities/channel.entity.ts
# src/services/channel.service.ts
# src/routes/channel.routes.ts

# 运行测试
pnpm test

# 类型检查
pnpm typecheck

UI包开发

cd packages/user-management-ui

# 编辑组件
# src/components/UsersTable.tsx

# 开发模式（如果有）
pnpm dev

# 类型检查
pnpm typecheck

开发小程序UI包

cd mini-ui-packages/yongren-dashboard-ui

# 编辑组件
# src/components/DashboardCard.tsx

# 构建包
pnpm build

# 运行测试
pnpm test

调试技巧

后端调试

使用 VS Code 调试

创建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Web Server",
      "runtimeExecutable": "pnpm",
      "runtimeArgs": ["run", "dev:web"],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal"
    }
  ]
}

日志调试

import { logger } from '@d8d/shared-utils';

// 使用logger而不是console.log
logger.info('User created', { userId: user.id });
logger.error('Failed to create order', { error });

前端调试

React DevTools

1. 安装 React DevTools 浏览器扩展
2. 在开发者工具中查看组件树和状态

网络请求调试

import { hc } from 'hono/client';
import type AppRoutes from '@d8d/server';

// 在客户端查看RPC调用
const client = hc<AppRoutes>('/api');

// 浏览器网络标签中查看请求

小程序调试

微信开发者工具

1. 打开微信开发者工具
2. 导入项目：选择 mini/ 或 mini-talent/ 目录
3. 使用调试工具查看组件和状态

H5 模式调试

在浏览器中打开：

• 员工小程序: http://localhost:8080
• 人才小程序: http://localhost:8081

测试

运行单元测试

# 运行所有测试
pnpm test

# 运行特定包的测试
cd packages/core-module/auth-module
pnpm test

# 监听模式
pnpm test:watch

运行集成测试

# 集成测试需要数据库连接
cd packages/core-module/auth-module
pnpm test:integration

运行E2E测试

# 在根目录
pnpm test:e2e

# 指定浏览器
pnpm test:e2e:chromium

测试覆盖率

pnpm test:coverage

数据库操作

运行迁移

# TypeORM迁移
cd web
pnpm db:migrate

数据库备份

# 备份数据库
pnpm db:backup

# 列出备份
pnpm db:backup:list

# 恢复数据库
pnpm db:restore

重置数据库

# ⚠️ 警告：这会删除所有数据
pnpm db:reset

常见任务

添加新的依赖

# 添加到根目录
pnpm add package-name

# 添加到特定包
cd packages/your-package
pnpm add package-name

# 添加开发依赖
pnpm add -D package-name

添加新的共享包

# 在 packages/ 或 allin-packages/ 创建新包
mkdir packages/new-package
cd packages/new-package

# 初始化 package.json
pnpm init

# 配置包导出
# ...

创建新的UI组件

# 在UI包中创建组件
cd packages/user-management-ui/src/components

# 创建组件文件
touch UserForm.tsx

性能优化

构建优化

# 使用 Turbo 缓存加速构建
pnpm build

# 清理缓存
rm -rf .turbo

开发模式优化

• 使用 --filter 只构建相关包

• 并行构建调整工作空间并发数

  # 只构建特定包
  pnpm --filter "@d8d/user-management-ui" build
  

故障排查

端口已被占用

# 查找占用端口的进程
lsof -i :8080

# 杀死进程
kill -9 <PID>

热重载不工作

1. 清理 .turbo 缓存
2. 重启开发服务器
3. 检查 vite.config.ts 配置

类型错误

# 清理并重新安装
rm -rf node_modules .pnpm-store
pnpm install

# 重置 TypeScript 项目服务
# 在 VS Code 中: Ctrl+Shift+P -> TypeScript: Restart TS Server

相关文档

• 开发环境设置
• 编码标准
• 测试规范

---

文档版本: 1.0 最后更新: 2026-01-07