df11ca0db6
1. 补充Windows下Volta安装后的生效方式说明 2. 完善不同环境下Node版本安装指引 3. 新增volta命令无法识别的问题排查方案 4. 在package.json中添加volta的node版本配置
358 lines
13 KiB
Markdown
358 lines
13 KiB
Markdown
# MES-UI
|
||
|
||
基于 [D2 Admin](https://github.com/d2-projects/d2-admin)（Vue 2.7 + Element UI）的企业级 MES 中后台前端项目。
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
本项目通过 **[Volta](https://volta.sh/)** 和 **[pnpm](https://pnpm.io/)** 锁定开发环境版本，确保团队成员使用完全一致的 Node.js 和包管理器版本。
|
||
|
||
| 工具 | 锁定版本 | 作用 |
|
||
| --- | --- | --- |
|
||
| **Node.js** | `18.16.0` | JavaScript 运行时（`.node-version` 文件） |
|
||
| **pnpm** | `10.33.0` | 包管理器（`package.json` → `packageManager` 字段） |
|
||
|
||
> 配置文件说明：
|
||
> - `.node-version` → Volta 读取，自动切换 Node.js 版本
|
||
> - `package.json` → `engines` 字段限制版本范围，`packageManager` 字段锁定 pnpm 版本
|
||
> - `.npmrc` → `engine-strict=true` 强制使用锁定版本，不满足则安装失败
|
||
|
||
---
|
||
|
||
## 从零开始安装到启动
|
||
|
||
### 第一步：安装 Volta（如果尚未安装）
|
||
|
||
Volta 会根据 `.node-version` 自动安装并切换到项目所需的 Node.js 版本。
|
||
|
||
**Windows（PowerShell）：**
|
||
|
||
```powershell
|
||
winget install Volta.Volta
|
||
```
|
||
|
||
> `winget` 安装完成后，**当前终端窗口不会自动加载 Volta**。选择以下任一方式生效：
|
||
>
|
||
> **方式一（关闭重开）：** 关掉当前终端，重新打开一个 PowerShell / VS Code 终端。
|
||
>
|
||
> **方式二（不重启立即生效）：** 在当前终端执行：
|
||
> ```powershell
|
||
> $env:PATH = [System.Environment]::GetEnvironmentVariable("PATH", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH", "User")
|
||
> ```
|
||
>
|
||
> 生效后验证：
|
||
> ```powershell
|
||
> volta --version # 应输出版本号（如 2.0.2）
|
||
> ```
|
||
|
||
**macOS / Linux：**
|
||
|
||
```bash
|
||
curl https://get.volta.sh | bash
|
||
# 重新加载 shell 配置
|
||
source ~/.bashrc # 或 source ~/.zshrc
|
||
volta --version
|
||
```
|
||
|
||
> 更多安装方式请参考 [Volta 官方文档](https://docs.volta.sh/guide/getting-started)。
|
||
|
||
### 第二步：启用 pnpm（Volta 内置支持，无需额外安装）
|
||
|
||
```bash
|
||
# Volta 会根据 package.json 中的 packageManager 字段
|
||
# 自动安装并使用 pnpm@10.33.0
|
||
volta install pnpm@10.33.0
|
||
|
||
# 验证版本
|
||
pnpm --version # 应输出 10.33.0
|
||
```
|
||
|
||
> 如果没有 Volta，也可以手动安装 pnpm：
|
||
> ```bash
|
||
> npm install -g pnpm@10.33.0
|
||
> ```
|
||
|
||
### 第三步：克隆项目并安装依赖
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone <仓库地址>
|
||
cd mes-ui
|
||
|
||
# Volta 检测到 .node-version 后，自动下载并安装 Node.js 18.16.0
|
||
# 如果你本机没有这个版本，Volta 会提示 "Fetching node@18.16.0" —— 等它完成即可
|
||
node --version # 应输出 v18.16.0
|
||
|
||
# 安装依赖
|
||
pnpm install
|
||
```
|
||
|
||
> **没有安装 Node 18.16.0 怎么办？**
|
||
> **Volta 用户**：无需手动操作。进入项目目录时 Volta 会自动检测 `.node-version`，如果本机缺这个版本，它会**自动下载安装**，你只需等待几秒终端提示完成即可。
|
||
> **nvm 用户**：执行 `nvm install 18.16.0 && nvm use 18.16.0`。
|
||
> **手动安装**：去 [nodejs.org](https://nodejs.org/) 下载 Node.js 18.16.0 安装包。
|
||
>
|
||
> 装完后建议运行 `node --version` 确认输出 `v18.16.0`，否则 `pnpm install` 会因为 `engine-strict=true` 直接报错拒绝安装。
|
||
|
||
### 第四步：配置环境变量
|
||
|
||
在项目根目录创建 `.env.development.local` 文件（此文件已在 `.gitignore` 中，不会提交）：
|
||
|
||
```bash
|
||
# 后台 API 地址
|
||
VUE_APP_API=http://你的后台服务器地址/
|
||
```
|
||
|
||
### 第五步：启动开发服务器
|
||
|
||
```bash
|
||
pnpm serve
|
||
```
|
||
|
||
浏览器会自动打开 `http://localhost:8080`（或终端提示的实际端口）。
|
||
|
||
---
|
||
|
||
## 常用命令速查
|
||
|
||
| 命令 | 说明 |
|
||
| --- | --- |
|
||
| `pnpm serve` | 启动开发服务器（自动打开浏览器） |
|
||
| `pnpm build` | 生产环境构建 |
|
||
| `pnpm build:preview` | 预发布环境构建 |
|
||
| `pnpm lint` | ESLint 代码检查并自动修复 |
|
||
| `pnpm test:unit` | 运行单元测试 |
|
||
| `pnpm install` | 安装依赖 |
|
||
| `pnpm add <包名>` | 添加新依赖（**禁止使用 npm install**） |
|
||
| `pnpm remove <包名>` | 移除依赖 |
|
||
|
||
---
|
||
|
||
## 版本锁定机制
|
||
|
||
### Node.js 版本锁定（Volta）
|
||
|
||
```
|
||
项目根目录
|
||
├── .node-version → 18.16.0（Volta 自动读取切换）
|
||
```
|
||
|
||
- Volta 进入项目目录时自动将 Node.js 切换为 `18.16.0`
|
||
- 如果该版本未安装，Volta 会自动下载并安装
|
||
- 传统方案（nvm）也兼容：`nvm use` 读取 `.nvmrc`，本项目同时提供 `.node-version` 供 Volta 使用
|
||
|
||
### pnpm 版本锁定
|
||
|
||
```
|
||
package.json
|
||
├── packageManager → pnpm@10.33.0（Corepack / Volta 识别）
|
||
├── engines.pnpm → >=10.33.0 <11（npm/pnpm install 时校验）
|
||
```
|
||
|
||
```ini
|
||
# .npmrc
|
||
engine-strict=true # 版本不满足 → 安装直接报错
|
||
```
|
||
|
||
### 依赖版本锁定
|
||
|
||
```
|
||
pnpm-lock.yaml → 锁定所有依赖的精确版本（等价于 npm 的 package-lock.json）
|
||
```
|
||
|
||
> `pnpm-lock.yaml` **必须提交到 Git**，保证所有环境安装的依赖版本完全一致。
|
||
|
||
---
|
||
|
||
## 项目目录结构
|
||
|
||
```
|
||
mes-ui/
|
||
├── .github/ # GitHub 相关配置
|
||
├── docs/ # 项目文档
|
||
├── public/ # 静态资源（不经过 webpack 处理）
|
||
├── src/ # PC 端业务源码
|
||
│ ├── api/ # 接口请求层（按业务模块拆分）
|
||
│ │ ├── _service.js # axios 请求服务实例
|
||
│ │ └── production-master-data/ # 生产主数据模块 API
|
||
│ ├── assets/ # 静态资源（经 webpack 处理，含 SCSS / SVG）
|
||
│ ├── components/ # 公共组件
|
||
│ │ ├── page-table/ # CRUD 表格便捷组合体
|
||
│ │ └── page-dialog-form/ # 新增/编辑弹框组件
|
||
│ ├── composables/ # 可复用逻辑函数
|
||
│ │ ├── useTableColumns.js # 列定义工厂
|
||
│ │ ├── useTableButtons.js # 按钮定义工厂
|
||
│ │ └── useI18n.js # i18n Mixin 工厂
|
||
│ ├── layout/ # 页面布局（header-aside）
|
||
│ ├── libs/ # 工具函数
|
||
│ ├── locales/ # 国际化语言包（zh-chs / en）
|
||
│ ├── router/ # 路由配置（modules/ 按业务模块拆分）
|
||
│ ├── store/ # Vuex 状态管理
|
||
│ ├── utils/ # 通用工具（文件下载、Excel 读取等）
|
||
│ └── views/ # 业务页面（按模块三级目录组织）
|
||
│ ├── production-master-data/ # 生产主数据
|
||
│ ├── system-administration/ # 系统管理
|
||
│ ├── equipment-management/ # 设备管理
|
||
│ ├── quality-management/ # 质量管控
|
||
│ ├── planning-production/ # 计划生产
|
||
│ └── data-platform/ # 数据平台
|
||
├── src.mobile/ # 移动端业务源码
|
||
├── .browserslistrc # 浏览器兼容配置
|
||
├── .editorconfig # 编辑器统一配置
|
||
├── .env / .env.development / .env.preview # 环境变量
|
||
├── .eslintignore / .eslintrc.js # ESLint 配置
|
||
├── .gitignore # Git 忽略配置
|
||
├── .node-version # Volta Node.js 版本锁定（18.16.0）
|
||
├── .npmrc # pnpm 配置（版本强校验）
|
||
├── .postcssrc.js # PostCSS 配置
|
||
├── babel.config.js # Babel 配置
|
||
├── jest.config.js # Jest 单元测试配置
|
||
├── jsconfig.json # VS Code 路径别名提示
|
||
├── package.json # 项目依赖与脚本
|
||
├── pnpm-lock.yaml # pnpm 依赖锁定文件（必须提交）
|
||
├── vue.config.js # Vue CLI 构建配置
|
||
└── README.md # 项目说明（本文件）
|
||
```
|
||
|
||
---
|
||
|
||
## 项目文档
|
||
|
||
| 文档 | 说明 |
|
||
| --- | --- |
|
||
| [表格组件使用说明](./docs/表格组件使用说明.md) | `page-table` + `page-dialog-form` 完整使用手册 |
|
||
| [国际化规则](./docs/国际化规则.md) | i18n 使用规范与迁移指南 |
|
||
| [迁移提示词](./docs/迁移提示词.md) | 旧页面迁移到新方案的规则文档 |
|
||
| [SCT基础表格重构设计](./docs/SCT基础表格重构设计.md) | 旧 `sct-base-table` → 新架构设计文档 |
|
||
| [变更日志](./docs/变更日志.md) | 项目变更日志 |
|
||
|
||
---
|
||
|
||
## 关键目录说明
|
||
|
||
### `src/components/` — 公共组件
|
||
|
||
| 组件 | 作用 |
|
||
| --- | --- |
|
||
| `page-table` | CRUD 表格组合体（按钮栏 + 表格 + 分页 + 高度自适应 + 帮助按钮） |
|
||
| `page-dialog-form` | 新增/编辑弹框（表单渲染 + 校验 + i18n 自动翻译） |
|
||
| `d2-container` | 页面容器（卡片、全屏、透明等多种布局变体） |
|
||
| `d2-container-frame` | iframe 嵌套外部页面容器 |
|
||
|
||
> `page-table` 和 `page-dialog-form` 是本项目核心组件，详细用法见 [表格组件使用说明](./docs/表格组件使用说明.md)。
|
||
|
||
### `src/composables/` — 逻辑复用层
|
||
|
||
| 文件 | 作用 |
|
||
| --- | --- |
|
||
| `useTableColumns.js` | 列定义工厂，消除手动分配 `idx`，约定 `prop: '_actions'` 为操作列 |
|
||
| `useTableButtons.js` | 按钮工厂，一键生成工具栏 + 行内按钮，自动注入权限过滤 |
|
||
| `useI18n.js` | i18n Mixin 工厂，通过 `i18nMixin(prefix)` 注入 `key()` / `ckey()` |
|
||
| `useConfirmHandle.js` | 确认操作 Mixin，封装 `$confirm` + API 调用 |
|
||
|
||
### `src/router/modules/` — 路由模块
|
||
|
||
按业务一级模块拆分，examples:
|
||
|
||
| 文件 | 路由前缀 | 对应模块 |
|
||
| --- | --- | --- |
|
||
| `production-master-data.js` | `/production_configuration` | 生产主数据 |
|
||
| `system-administration.js` | `/system_settings` | 系统管理 |
|
||
| `equipment-management.js` | `/equipment_management` | 设备管理 |
|
||
| `quality-management.js` | `/quality_management` | 质量管控 |
|
||
| `planning-production.js` | `/planning_production` | 计划生产 |
|
||
| `data-platform.js` | `/data_platform` | 数据平台 |
|
||
|
||
### `src/api/` — 接口请求层
|
||
|
||
按业务模块父目录存放，命名规则：`{模块名}.js`。例如：
|
||
- `production-master-data/device-category.js` → 设备类型
|
||
- `production-master-data/factory-area.js` → 工厂区域
|
||
|
||
---
|
||
|
||
## 构建配置文件
|
||
|
||
| 文件 | 作用 |
|
||
| --- | --- |
|
||
| `vue.config.js` | Vue CLI 构建配置（多页入口、CDN、webpack 插件、主题色替换、SVG sprites、路径别名） |
|
||
| `babel.config.js` | Babel 转译配置 |
|
||
| `.postcssrc.js` | PostCSS 自动前缀等配置 |
|
||
| `.eslintrc.js` | ESLint 代码规范 |
|
||
| `jest.config.js` | 单元测试框架配置 |
|
||
| `jsconfig.json` | VS Code 路径别名智能提示（`@` → `src/`） |
|
||
| `.browserslistrc` | 目标浏览器范围 |
|
||
| `.editorconfig` | 编辑器缩进/换行风格统一 |
|
||
|
||
---
|
||
|
||
## 环境变量
|
||
|
||
| 文件 | 说明 |
|
||
| --- | --- |
|
||
| `.env` | 所有环境通用变量 |
|
||
| `.env.development` | 开发环境变量 |
|
||
| `.env.development.local` | 本地开发环境变量（不提交 Git，需自行创建） |
|
||
| `.env.preview` | 预发布环境变量 |
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1：`pnpm install` 报错 "Unsupported engine"
|
||
|
||
> 意思：本机 Node.js 或 pnpm 版本不在项目规定范围内，install 被阻断。
|
||
|
||
**先排查版本：**
|
||
|
||
```bash
|
||
node --version # 项目要求 >=18.16.0 <19
|
||
pnpm --version # 项目要求 >=10.33.0 <11
|
||
```
|
||
|
||
**谁把版本不对：**
|
||
|
||
| 情景 | 解决办法 |
|
||
| --- | --- |
|
||
| **用 Volta**（推荐） | `volta install node@18.16.0` + `volta install pnpm@10.33.0`，进入项目目录自动生效 |
|
||
| **用 nvm** | `nvm install 18.16.0 && nvm use 18.16.0`，再 `npm install -g pnpm@10.33.0` |
|
||
| **手动安装** | 去 [nodejs.org](https://nodejs.org/) 下载 18.16.0，再 `npm install -g pnpm@10.33.0` |
|
||
| **已有正确版本但切换不生效** | 重新打开终端，确保 `volta` / `nvm` 已正确加载 |
|
||
|
||
> 版本验证通过后，重新执行 `pnpm install`。
|
||
|
||
### Q2：启动后页面报跨域错误
|
||
|
||
在 `.env.development.local` 中确认 `VUE_APP_API` 指向正确的后台地址，且后台已开启 CORS。
|
||
|
||
### Q3：端口被占用
|
||
|
||
默认端口为 `8080`。如需修改，在 `.env.development.local` 中添加：
|
||
|
||
```bash
|
||
PORT=8081
|
||
```
|
||
|
||
### Q4：`volta` 命令无法识别 / "无法将 volta 项识别为 cmdlet"
|
||
|
||
> 原因：`winget install Volta.Volta` 不会自动刷新当前终端的 PATH 缓存。
|
||
|
||
**解决办法二选一：**
|
||
|
||
```powershell
|
||
# 方案 A：关掉当前终端，重新打开一个（推荐，最简单）
|
||
# 方案 B：在当前终端执行以下命令立即生效，免重启
|
||
$env:PATH = [System.Environment]::GetEnvironmentVariable("PATH", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH", "User")
|
||
```
|
||
|
||
> 生效后 `volta --version` 应输出版本号。
|
||
|
||
### Q5：依赖安装慢
|
||
|
||
pnpm 默认使用 npm registry。如需加速，可配置镜像：
|
||
|
||
```bash
|
||
pnpm config set registry https://registry.npmmirror.com
|
||
```
|