基于Midwayjs的管理系统-开发环境

J_TsMask
505 阅读4分钟

基于Midwayjs的管理系统-开发环境

本文用于说明本地开发环境的准备方式，帮助你快速把后端项目跑起来。

因为本项目采用前后端分离架构，若需要完整联调体验，需要分别启动后端 API 服务和前端页面服务。
本文重点介绍后端 mask_api_midwayjs 的开发环境搭建。

基础环境要求

后端项目当前要求如下：

工具说明最低版本
Node.js后端运行环境24+
MySQL业务主数据库8+
Redis缓存支撑6+

建议先确认版本：

node -v
npm -v

如果你使用 nvm / fnm 等 Node 版本管理工具，建议直接切到 24.x 及以上版本。

npm 源说明

国内网络环境下载依赖较慢时，可临时或长期使用镜像源。

常用源如下：

  • 腾讯源：https://mirrors.cloud.tencent.com/npm/
  • 淘宝源：https://registry.npmmirror.com
  • 官方源：https://registry.npmjs.org/

示例：

# 临时使用
npm install --registry https://registry.npmmirror.com

# 设置默认源（可选）
npm config set registry https://registry.npmmirror.com

后端项目开发流程

仓库地址：mask_api_midwayjs

1. 拉取代码

git clone https://gitee.com/TsMask/mask_api_midwayjs
cd mask_api_midwayjs

2. 初始化数据库

数据库初始化脚本位于 script 目录：

  • script/db_init.sql
  • script/db_init_demo.sql

你可以先执行主初始化脚本；如果需要演示数据，再执行 demo 脚本。

建议使用 MySQL 客户端（如 Navicat、DBeaver、DataGrip）执行脚本：

  1. 创建数据库
  2. 执行初始化 SQL
  3. 检查表与基础数据是否导入成功

3. 配置环境变量

后端项目当前采用 .env 方式管理运行依赖信息，主要包含：

  • 服务端口
  • JWT 配置
  • MySQL 配置
  • Redis 配置

请根据实际环境准备以下文件：

  • .env.example：变量模板，可提交到 Git
  • .env.development：本地开发配置，不提交
  • .env.production：生产环境配置，不提交

开发阶段请基于模板创建本地配置：

cp .env.example .env.development

随后填写真实的本地开发参数，例如：

  • DB_HOST
  • DB_PORT
  • DB_USERNAME
  • DB_PASSWORD
  • DB_DATABASE
  • REDIS_HOST
  • REDIS_PASSWORD
  • JWT_SECRET

4. 了解应用层配置

应用层配置放在 src/config 目录，用于区分默认配置与环境差异配置：

  • config.default.ts：公共默认配置
  • config.local.ts：本地开发差异配置
  • config.unittest.ts：测试环境差异配置

说明：

  • .env 主要承载数据库、Redis、JWT 等外部运行依赖信息
  • src/config 主要承载框架行为、业务运行参数、日志级别等应用配置

两者配合使用，避免把敏感信息直接写死在代码中。

5. 安装依赖

npm install

6. 启动开发服务

npm run dev

启动成功后，通常会看到类似信息：

http://127.0.0.1:6275

说明本地后端服务已经运行。

常用开发命令

# 本地开发
npm run dev

# 构建
npm run build

# 单元测试
npm run test

# 测试覆盖率
npm run cov

# 代码检查
npm run lint

# 自动修复格式问题
npm run lint:fix

开发环境常见问题

1. Node 版本不符合要求

当前项目要求 Node.js >= 24。
如果版本过低，可能会出现依赖安装失败或运行异常。

2. MySQL 连接失败

请检查：

  • 数据库是否启动
  • .env.development 中 DB_HOST、DB_PORT、DB_DATABASE 是否正确
  • 用户名和密码是否正确
  • 是否已完成 db_init.sql 初始化

3. Redis 连接失败

请检查：

  • Redis 是否启动
  • .env.development 中 REDIS_HOST、REDIS_PORT、REDIS_PASSWORD 是否正确
  • 本地是否被防火墙或网络策略限制

4. JWT 配置缺失

如果启动或登录异常，请确认 .env.development 中已配置：

  • JWT_SECRET
  • JWT_EXPIRES_IN
  • JWT_REFRESH_EXPIRES_IN

5. 静态目录权限或路径问题

项目启动时会检查并初始化静态目录。
若目录不可写或路径配置错误，可能会导致启动阶段报错。

前端联调说明

若你需要完整前后端联调，可单独启动前端项目。

常见前端仓库包括：

前端一般需要：

  1. 拉取前端代码
  2. 安装前端依赖
  3. 修改前端代理配置，使其指向本地后端地址
  4. 启动前端开发服务
  5. 在浏览器访问前端页面进行登录和功能验证

建议的本地开发顺序

如果你是第一次接触本项目，建议按以下顺序操作：

  1. 先确认 Node.js 版本
  2. 再准备 MySQL 与 Redis
  3. 再创建 .env.development
  4. 再执行数据库初始化
  5. 再执行 npm install
  6. 最后执行 npm run dev

这样可以减少“依赖装好了但连不上服务”的排查成本。

结语

本文档目标是帮助你快速搭建本地开发环境。
如果你后续需要了解生产部署方式，可继续阅读项目中的 Linux / Docker / 宝塔部署文档。

avatar
文章
阅读
粉丝