mmsAdmin

简体中文

English

简体中文

English

主题

MMS-UI 项目使用指南 ​

📖 目录 ​

🎯 项目概述 ​

MMS-UI 是一个基于 Vue3 + TypeScript + Vite 技术栈的现代化前端项目，使用 Element Plus UI 组件库构建。项目提供了完整的开发环境管理工具和丰富的功能特性。

核心特性 ​

  • 🚀 现代技术栈: Vue3 + TypeScript + Vite
  • 🎨 UI 组件库: Element Plus
  • 🛠️ 开发工具: 完整的脚本化开发环境管理
  • 📦 包管理器: 支持 npm/pnpm 多种方式
  • 🌐 镜像加速: 内置淘宝镜像配置
  • 🔧 代码质量: ESLint + Prettier + TypeScript 检查
  • 💾 缓存管理: 智能缓存清理功能

🔧 环境要求 ​

最低要求 ​

  • Node.js: ≥ 18.0.0
  • npm: ≥ 8.0.0
  • 操作系统: Windows / macOS / Linux

推荐配置 ​

  • Node.js: 20.19.5 (LTS)
  • 包管理器: pnpm (推荐)
  • IDE: VS Code / WebStorm

🚀 快速开始 ​

1. 环境检查 ​

bash
# 检查 Node.js 版本
node --version

# 检查 npm 版本
npm --version

2. 使用开发工具菜单（推荐） ​

项目提供了强大的综合开发工具菜单，可以一键完成环境配置：

bash
npm run mms

# 或
./scripts/mms.sh
bash
npm run mms:win

# 或
powershell -ExecutionPolicy Bypass -File ./scripts/mms.ps1

3. 手动安装依赖 ​

bash
# 使用 npm（淘宝镜像加速）
npm run install:fast

# 使用 pnpm（推荐）
npm run pnpm:setup  # 首次安装 pnpm
pnpm install

4. 启动开发服务器 ​

bash
# 使用 npm
npm run dev

# 使用 pnpm
pnpm dev

# 使用一键启动脚本
npm run start:pnpm

5. 访问应用 ​

开发服务器启动后，自动打开浏览器访问：

  • 默认地址: http://localhost:80
  • 如端口被占用，会自动尝试其他端口

🛠️ 开发工具菜单 ​

项目内置了强大的综合开发工具菜单，提供以下功能模块：

主要功能 ​

1. Node.js 环境管理 (NVM) ​

  • 🔧 安装 NVM（支持多种安装方式）
  • 📦 安装推荐 Node.js 版本
  • 🔄 安装最新 LTS Node.js
  • 🔀 切换 Node.js 版本
  • 📋 查看已安装版本
  • ⚙️ 设置默认版本
  • ⬆️ 升级 npm

2. 镜像源配置与加速 ​

  • 🚀 一键配置淘宝镜像（推荐）
  • ✅ 验证镜像配置
  • ⚡ 测试镜像速度
  • 🔄 切换到官方镜像
  • 📎 配置 PNPM 镜像
  • 📊 显示当前镜像配置
  • 🏆 镜像源对比测试

3. 依赖安装与管理 ​

  • 📦 NPM 快速安装依赖
  • 🚀 PNPM 快速安装依赖
  • ⬇️ 安装 PNPM
  • 🔒 检查依赖安全漏洞
  • ⬆️ 更新依赖到最新版本
  • 📊 分析依赖包大小
  • 🧹 清理未使用的依赖

4. 项目启动与构建 ​

  • 🚀 启动开发服务器（npm/pnpm）
  • 📜 一键启动脚本
  • 🏗️ 构建生产版本
  • 👀 预览构建结果
  • 🔧 开发环境构建
  • 📝 TypeScript 类型检查

5. 代码质量检查与修复 ​

  • 🔍 ESLint 代码检查
  • 🔧 ESLint 自动修复
  • 💄 Prettier 代码格式化
  • ✅ Prettier 格式化检查
  • 🎯 组合检查（Lint + Format）
  • 📋 Git 提交前检查
  • 📄 批量格式化 Vue 文件

6. 环境诊断与优化 ​

  • 🔬 完整环境检查
  • 🌐 网络连接诊断
  • 🔌 端口占用检查
  • 💾 磁盘空间检查
  • 🔐 权限问题诊断
  • 📋 生成诊断报告
  • ⚡ 性能优化建议

7. 缓存清理与重置 ​

  • 🗑️ 清理 npm 缓存
  • 🗑️ 清理 pnpm 缓存
  • 📁 清理 node_modules
  • 🏗️ 清理构建缓存
  • 🔒 清理 lock 文件
  • 🔄 完全重置项目
  • 🧹 清理系统临时文件

8. 项目信息与帮助 ​

  • ℹ️ 查看项目详细信息
  • 📋 查看依赖列表
  • 📜 查看脚本命令
  • ⚙️ 查看配置文件
  • ❓ 常见问题解答
  • 📝 查看更新日志
  • 📊 生成项目报告

📁 项目结构 ​

mms-ui/
├── public/                 # 静态资源
├── src/                    # 源代码
│   ├── components/         # 公共组件
│   ├── views/             # 页面组件
│   ├── styles/            # 样式文件
│   │   └── mms.scss       # 工具类样式库
│   ├── utils/             # 工具函数
│   ├── stores/            # Pinia 状态管理
│   ├── router/            # 路由配置
│   └── types/             # TypeScript 类型定义
├── scripts/               # 开发脚本
│   ├── mms.sh             # Linux/macOS 开发工具菜单
│   ├── mms.ps1            # Windows 开发工具菜单
│   ├── start-pnpm.sh      # 一键启动脚本
│   ├── setup-npm-mirrors.sh # 镜像配置脚本
│   └── verify-mirrors.sh  # 镜像验证脚本
├── package.json           # 项目配置
├── vite.config.ts         # Vite 配置
├── tsconfig.json          # TypeScript 配置
└── README.md              # 项目说明

💻 开发指南 ​

样式开发 ​

项目使用自定义的工具类样式库 mms.scss，具有以下特点：

  • 🎨 协同设计: 与 WindiCSS 协同工作，避免命名冲突
  • 📏 统一数值: 采用 4px 递增的统一数值体系
  • 📱 响应式: 支持 mobile、tablet、desktop 三种断点
scss
// 使用示例
.m-4    // margin: 16px (4 * 4)
.p-8    // padding: 32px (8 * 4)
.text-mobile   // 移动端样式
.text-tablet   // 平板样式
.text-desktop  // 桌面样式

代码规范 ​

项目配置了完整的代码质量检查工具：

bash
# ESLint 检查
npm run lint

# 自动修复
npm run lint:fix

# Prettier 格式化
npm run format

# 格式化检查
npm run format:check

# TypeScript 类型检查
npm run type-check

# 组合检查
npm run format:lint

# Git 提交前检查
npm run pre-commit

开发流程 ​

  1. 创建功能分支

    bash
    git checkout -b feature/your-feature-name

  2. 开发前检查

    bash
    # 使用开发工具菜单进行环境检查
./scripts/mms.sh

  3. 启动开发服务器

    bash
    npm run start:pnpm  # 推荐使用一键启动脚本

  4. 代码开发

    • 遵循 Vue3 Composition API 规范
    • 使用 TypeScript 进行类型检查
    • 遵循 ESLint 和 Prettier 规范

  5. 提交前检查

    bash
    npm run pre-commit

  6. 提交代码

    bash
    git add .
git commit -m "feat: your feature description"
git push origin feature/your-feature-name

🏗️ 构建部署 ​

开发环境构建 ​

bash
npm run build:dev

生产环境构建 ​

bash
npm run build

预览构建结果 ​

bash
npm run preview

构建输出 ​

构建文件将输出到 dist/ 目录：

dist/
├── assets/
│   ├── js/         # JavaScript 文件
│   ├── css/        # CSS 文件
│   └── img/        # 图片资源
└── index.html      # 入口文件

🔍 常见问题 ​

1. 依赖安装失败 ​

问题: npm install 或 pnpm install 失败

解决方案:

bash
# 使用开发工具菜单的镜像配置
./scripts/mms.sh
# 选择 "2) 镜像源配置与加速" -> "1) 一键配置淘宝镜像"

# 或手动配置镜像
npm run mirror:setup

2. 端口被占用 ​

问题: 开发服务器启动时端口被占用

解决方案:

  • Vite 会自动尝试其他可用端口
  • 或手动指定端口：npm run dev -- --port 3000

3. 缓存相关问题 ​

问题: 依赖更新后出现异常

解决方案:

bash
# 使用开发工具菜单的缓存清理功能
./scripts/mms.sh
# 选择 "7) 缓存清理与重置" -> "6) 完全重置项目"

4. TypeScript 类型错误 ​

问题: TypeScript 类型检查失败

解决方案:

bash
# 运行类型检查
npm run type-check

# 检查 tsconfig.json 配置
# 确保所有依赖的类型定义已安装

5. vue-demi 解析错误 ​

问题: Failed to resolve import "vue-demi"

解决方案:

  • 该问题已在 vite.config.ts 中修复
  • 如遇到类似问题，使用缓存清理功能

⚡ 性能优化 ​

1. 依赖优化 ​

  • 使用 pnpm 包管理器提升安装速度
  • 配置淘宝镜像加速依赖下载
  • 定期清理无用依赖

2. 构建优化 ​

  • Vite 预构建优化
  • 代码分割和懒加载
  • 资源压缩和优化

3. 开发体验优化 ​

  • HMR (Hot Module Replacement) 热更新
  • TypeScript 类型检查
  • ESLint 和 Prettier 代码规范

4. 监控和诊断 ​

使用开发工具菜单的环境诊断功能：

  • 网络连接诊断
  • 磁盘空间检查
  • 性能优化建议

📞 技术支持 ​

如果您在使用过程中遇到问题：

  1. 首先查阅本使用指南
  2. 使用开发工具菜单进行环境诊断
  3. 检查常见问题解答
  4. 查看项目 README.md 文件
  5. 联系技术支持团队

版本: v1.0.8
更新时间: 2024年9月
技术栈: Vue3 + TypeScript + Vite + Element Plus

Released under the MIT License.

Copyright © 2021-present 品创网络 · XiJue