DM-ROW 接口文档

Appearance

开发环境配置 ​

**本文引用的文件** - [app/devicemate-app/package.json](file://app/devicemate-app/package.json) - [dm/lemes-web/package.json](file://dm/lemes-web/package.json) - [app/devicemate-app/.hbuilderx/launch.json](file://app/devicemate-app/.hbuilderx/launch.json) - [app/devicemate-app/vue.config.js](file://app/devicemate-app/vue.config.js) - [dm/lemes-web/vue.config.js](file://dm/lemes-web/vue.config.js) - [app/devicemate-app/pages.json](file://app/devicemate-app/pages.json) - [app/devicemate-app/.gitignore](file://app/devicemate-app/.gitignore) - [dm/lemes-web/.eslintrc.js](file://dm/lemes-web/.eslintrc.js) - [dm/lemes-web/.prettierrc](file://dm/lemes-web/.prettierrc) - [dm/lemes-web/babel.config.js](file://dm/lemes-web/babel.config.js) - [dm/lemes-web/postcss.config.js](file://dm/lemes-web/postcss.config.js) - [dm/lemes-web/tailwind.config.js](file://dm/lemes-web/tailwind.config.js) - [dm/lemes-web/jest.config.js](file://dm/lemes-web/jest.config.js) - [dm/lemes-web/src/settings.js](file://dm/lemes-web/src/settings.js)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介 ​

本指南面向 DeviceMate 项目的前端与全栈开发者，提供从零搭建高效开发环境的完整步骤，涵盖以下主题：

  • Node.js 与包管理器（npm/pnpm）安装与配置
  • HBuilder X 开发工具安装、配置与使用技巧
  • VS Code 编辑器推荐插件、代码格式化与调试配置
  • 项目依赖安装、开发服务器启动与热重载配置
  • 环境变量、代理设置与跨域处理
  • Git 版本控制、代码规范检查与自动化构建
  • 常见开发环境问题排查与解决方案

项目结构 ​

DeviceMate 仓库包含多端前端与后端模块，其中与前端开发环境最相关的是：

  • uni-app 移动端/H5 应用：app/devicemate-app
  • Vue2 Web 管理后台：dm/lemes-web

图表来源

章节来源

核心组件 ​

  • 包管理与脚本
    • uni-app 项目：依赖较少，主要通过脚本进行打包与运行（当前仅定义了测试脚本占位）
    • Web 管理后台：提供 dev/build/lint/test 等完整脚本，集成 ESLint、Jest、Plop 等工具链
  • 开发服务器与代理
    • uni-app：内置开发服务器端口与代理配置，便于联调后端接口
    • Web 管理后台：支持多目标代理、Mock、Gzip 压缩、主题色替换等高级特性
  • 页面与导航
    • uni-app 使用 pages.json 统一声明页面与 tabbar，便于多端统一管理
  • 质量保障
    • ESLint、Prettier、Jest、Husky/Lint-Staged 等工具链在 Web 项目中已配置

章节来源

架构总览 ​

下图展示两个前端子项目的开发与构建路径，以及与工具链的关系。

图表来源

详细组件分析 ​

Node.js 与包管理器（npm/pnpm） ​

  • Node.js 版本要求
    • Web 项目明确声明最低 Node 版本与 npm 版本要求，建议优先满足 engines 字段
  • 包管理器选择
    • 推荐使用 pnpm 以获得更快的安装速度与更严格的依赖隔离；如使用 npm，请确保版本满足 engines 要求
  • 全局安装与缓存
    • 建议开启 pnpm/npx 缓存，避免重复下载依赖
  • 依赖安装
    • 在根目录执行安装命令，自动解析子项目依赖
  • 常见问题
    • 权限不足导致安装失败：使用 sudo 或调整 npm/pnpm 缓存目录权限
    • 网络超时：切换至国内镜像源或使用 pnpm 的 registry 配置

章节来源

HBuilder X 开发工具 ​

  • 安装与启动
    • 安装完成后，导入 uni-app 项目根目录，首次打开可能需要等待资源初始化
  • 启动配置
    • 通过 .hbuilderx/launch.json 指定运行目标（如 App Android），可直接在 IDE 内预览与调试
  • 使用技巧
    • 使用“真机调试”功能配合手机热点，快速验证跨端兼容性
    • 利用 IDE 的“条件断点”与“函数断点”定位复杂逻辑问题
    • 结合 uni-app 的编译输出目录，清理 unpackage 后再重新编译，避免缓存干扰

章节来源

VS Code 编辑器 ​

  • 推荐插件
    • ESLint：与项目 ESLint 规则联动，实时提示
    • Prettier：统一代码风格，建议与保存时格式化结合
    • Vue Language Features (Volar)：提供 Vue2/3 语法高亮与智能提示
    • Auto Rename Tag：HTML/XML 标签自动重命名
    • Path Intellisense：路径补全
    • Bracket Pair Colorizer：括号配对高亮
  • 代码格式化
    • 使用 .prettierrc 统一分号与单引号策略
    • 在 VS Code 设置中启用“保存时格式化”，并与 ESLint 配合
  • 调试配置
    • Web 项目可使用浏览器扩展或 VS Code Live Server 预览静态页面
    • uni-app 项目建议通过 HBuilder X 或命令行启动开发服务器进行调试

章节来源

依赖安装与开发服务器 ​

  • 依赖安装
    • 在项目根目录执行安装命令，确保子项目依赖完整
  • 开发服务器
    • uni-app：默认端口 8081，可通过 vue.config.js 修改
    • Web：默认端口 9527，可通过 vue.config.js 修改
  • 热重载
    • 两项目均基于 Vue CLI，具备热重载能力；若热更新不生效，尝试重启开发服务器

章节来源

环境变量、代理与跨域 ​

  • uni-app 代理
    • 在 vue.config.js 中配置 /lemes-api 代理，将请求转发至后端服务，支持 ws 与路径重写
  • Web 代理
    • 支持多目标代理，包括本地 Mock、远程后端、OSS 与第三方系统
    • 可通过环境变量注入 dev-ip、smart-connect 等头信息，便于后端识别
  • 跨域处理
    • 通过 changeOrigin 与 headers 配置，解决跨域与鉴权头传递问题
  • 环境变量
    • Web 项目需正确配置 .env.development 示例文件，确保 VUE_APP_* 变量存在

图表来源

章节来源

Git 版本控制、代码规范与自动化构建 ​

  • Git
    • .gitignore 已忽略 node_modules、dist、日志与 IDE 临时文件，建议按需添加子模块忽略规则
  • 代码规范
    • ESLint 规则已在 .eslintrc.js 中定义，支持 Vue 推荐规则与自定义规则
    • Prettier 通过 .prettierrc 统一风格
    • Husky + Lint-Staged 在提交前自动格式化与检查，减少 CI 失败
  • 自动化构建
    • Web 项目提供 build 脚本，支持 Gzip 压缩与主题色替换插件
    • Jest 提供单元测试配置，支持覆盖率统计

章节来源

依赖关系分析 ​

  • uni-app 项目
    • 依赖较少，主要通过脚本与 vue.config.js 驱动开发与构建
  • Web 项目
    • 依赖丰富，涵盖 UI、图表、富文本、Mock、测试、构建优化等模块
    • 通过 vue.config.js 集成代理、Gzip、主题色替换、缓存优化等能力

图表来源

章节来源

性能考虑 ​

  • 构建优化
    • Web 项目已启用 Gzip 压缩与分包策略，建议在生产环境开启对应配置
    • 主题色替换插件按需生成样式文件，避免全量引入
  • 开发体验
    • HardSourceWebpackPlugin 与缓存加载器提升开发阶段编译速度
    • Source Map 在开发阶段启用，便于调试
  • 图片与资源
    • 图片按阈值转换为 base64，减少请求数量；大图使用 file-loader 输出

章节来源

故障排查指南 ​

  • 依赖安装失败
  • 端口占用
    • uni-app 默认 8081，Web 默认 9527；修改 vue.config.js 中的 port 并重启
  • 代理不生效
    • 检查 vue.config.js 中的 target、pathRewrite、changeOrigin 是否正确
    • 确认后端 CORS 配置允许前端来源与头信息
  • 热重载失效
    • 关闭 overlay 或降低日志级别；必要时重启开发服务器
  • ESLint 报错
    • 在 VS Code 中安装 ESLint 插件并启用“保存时修复”
    • 检查 .eslintrc.js 规则是否与团队约定一致
  • Jest 测试失败
    • 确保 jest.config.js 中的模块映射与转换规则与项目结构匹配
    • 清理 tests/unit/coverage 目录后重新运行测试

章节来源

结论 ​

通过以上配置与最佳实践，开发者可在本地快速搭建稳定高效的开发环境。建议：

  • 统一使用 pnpm 并配置镜像源
  • 严格遵循 ESLint 与 Prettier 规范
  • 合理利用代理与环境变量，确保前后端联调顺畅
  • 在开发阶段充分利用缓存与热重载，在生产阶段启用 Gzip 与分包优化

附录 ​

  • 快速启动清单
    • 安装 Node.js（满足 engines 要求）
    • 安装 pnpm 并配置镜像源
    • 在项目根目录执行依赖安装
    • 分别启动 uni-app（8081）与 Web（9527）开发服务器
    • 配置 HBuilder X 启动目标并进行真机调试
    • 使用 VS Code 插件保证代码质量与一致性