🛠️ 开发工具与脚本文档

l-pc-front 项目开发工具、脚本与环境配置指南

📋 开发工具概览

核心开发环境

工具名称	版本要求	用途说明
Node.js	18.20.8	运行环境
Yarn	1.22.22	包管理工具
Vue CLI	3.12.1	项目构建工具
Git	2.0+	版本控制

辅助开发工具

工具名称	用途说明
VS Code	代码编辑器
Vue DevTools	Vue 调试工具
Chrome DevTools	浏览器调试工具
ESLint	代码质量检查
Prettier	代码格式化

📜 脚本文件详解

1. 版本生成脚本 (`generate-version.js`)

文件路径: scripts/generate-version.js

功能: 生成项目版本信息文件，包含版本号、构建号、构建时间等信息

核心功能:

从 Git 仓库获取最近的 Tag 作为版本号
获取 Git Commit Hash 作为构建号
获取 Git 提交时间和构建时间
生成 public/version.json 文件

使用方法:

bash

# 直接运行
node scripts/generate-version.js

# 或通过 npm 脚本运行
npm run generate-version

生成的版本文件示例:

json

{
  "version": "v1.0.0",
  "build": "a1b2c3d",
  "commitTime": "2025-12-20T10:30:00+08:00",
  "buildTime": "2025-12-20 14:30:00",
  "tagDescription": "初始版本发布"
}

2. Git Tag 提交工具 (`git-tag-cli.js`)

文件路径: scripts/git-tag-cli.js

功能: 交互式 Git Tag 提交工具，简化标签的创建和推送流程

核心功能:

检查当前分支和未提交的更改
自动生成下一个版本号建议
验证语义化版本格式
创建并推送 Git 标签
可选生成版本文件
可选构建项目

使用方法:

bash

# 直接运行
node scripts/git-tag-cli.js

# 或通过 npm 脚本运行
npm run tag

使用流程:

检查当前分支和未提交更改
自动生成下一个版本号建议
询问用户输入版本号和描述
确认操作并创建标签
推送标签到远程仓库
可选生成版本文件和构建项目

示例输出:

🚀 Git Tag 提交工具
==================
当前分支: master
建议版本号: v1.0.1
请输入版本号 (默认: v1.0.1) 
请输入标签描述 (可选) 修复了一些bug

📋 操作确认
版本号: v1.0.1
标签描述: 修复了一些bug
当前分支: master
是否确认创建并推送标签? (y/N) y

📦 创建本地标签...
✅ 本地标签 v1.0.1 创建成功

📤 推送标签到远程...
✅ 标签 v1.0.1 推送成功

📄 生成版本文件...
✅ Version file generated:
{
  "version": "v1.0.1",
  "build": "a1b2c3d",
  "commitTime": "2025-12-20T10:30:00+08:00",
  "buildTime": "2025-12-20 14:30:00",
  "tagDescription": "修复了一些bug"
}

🎉 标签提交完成!
版本号: v1.0.1
远程地址: https://gitee.com/njy_3/l-pc-front/releases/tag/v1.0.1

⚙️ 环境配置

1. 环境变量文件

项目支持多环境配置，通过 .env 文件进行管理。

主要环境变量文件

文件名	用途说明
`.env`	基础环境配置
`.env.audit`	稽核环境配置
`.env.auditDev`	稽核开发环境配置
`.env.debug`	调试环境配置
`.env.park`	园区环境配置
`env.example`	环境变量示例

环境变量示例

bash

# env.example
# 基础URL
VUE_APP_BASE_URL=http://localhost:8080

# API网关地址
VUE_APP_GATEWAY_URL=http://localhost:8080/api

# 环境标识
VUE_APP_ENV=development

# 调试模式
VUE_APP_DEBUG=true

2. 配置文件

构建配置文件

文件名	用途说明
`public/config/config_build.js`	生产环境配置
`public/config/config_dev.js`	开发环境配置

构建配置示例

javascript

// config_dev.js
window.APP_CONFIG = {
  // 服务器地址
  serverUrl: 'http://localhost:8080',
  // API地址
  API_URL: 'http://localhost:8080/api',
  // 静态资源CDN
  CDN_URL: '',
  // 应用名称
  APP_NAME: 'l-pc-front',
  // 调试模式
  DEBUG: true,
  // 版本号
  VERSION: '1.0.0'
};

🚀 构建命令

1. 基础构建命令

命令	用途说明
`yarn install`	安装依赖
`yarn serve`	启动开发服务器
`yarn build`	构建生产版本
`yarn build:audit`	构建稽核环境版本
`yarn build:debug`	构建调试环境版本
`yarn build:version`	构建带版本号的版本
`yarn build-lib`	构建为库模式
`yarn build-lib4app`	构建为APP库模式

2. 开发命令

命令	用途说明
`yarn dev`	启动标准开发服务器
`yarn dev:park`	启动园区开发服务器
`yarn lint`	代码质量检查
`yarn test`	运行测试

3. 脚本命令

命令	用途说明
`yarn generate-version`	生成版本文件
`yarn tag`	运行 Git Tag 提交工具

4. 构建命令详解

`yarn serve`

用途: 启动开发服务器，支持热更新

主要特性:

支持热更新
自动打开浏览器
提供开发环境调试工具
支持代理配置

示例:

bash

yarn serve

`yarn build`

用途: 构建生产版本

主要特性:

代码压缩和优化
资源哈希处理
移除调试代码
生成可部署的静态文件

示例:

bash

yarn build

`yarn build:version`

用途: 构建带版本号的版本，自动生成版本文件

主要特性:

生成 public/version.json 文件
包含版本号、构建号、构建时间等信息
便于版本管理和问题定位

示例:

bash

yarn build:version

`yarn tag`

用途: 运行 Git Tag 提交工具，简化标签创建和推送流程

主要特性:

自动生成下一个版本号建议
验证语义化版本格式
支持标签描述
自动推送标签到远程仓库
可选生成版本文件和构建项目

示例:

bash

yarn tag

🔧 开发流程

1. 本地开发

步骤1: 克隆代码

bash

git clone https://gitee.com/njy_3/l-pc-front.git
cd l-pc-front

步骤2: 安装依赖

bash

yarn install

步骤3: 启动开发服务器

bash

# 标准开发环境
yarn dev

# 或
# 园区开发环境
yarn dev:park

步骤4: 访问应用

打开浏览器访问: http://localhost:8080

2. 代码提交

步骤1: 检查代码质量

bash

yarn lint

步骤2: 提交代码

bash

git add .
git commit -m "提交信息"

步骤3: 推送代码

bash

git push origin master

3. 版本发布

使用 yarn tag 命令进行版本发布，该命令会自动完成以下操作:

检查当前分支和未提交更改
自动生成下一个版本号建议
创建并推送 Git 标签
生成版本文件
可选构建项目

示例:

bash

yarn tag

4. 构建部署

步骤1: 构建生产版本

bash

yarn build

# 或构建带版本号的版本
yarn build:version

步骤2: 部署构建产物

构建产物位于 dist 目录，将该目录下的文件部署到服务器即可。

📝 开发规范

1. 代码规范

使用 ESLint 进行代码质量检查
使用 Prettier 进行代码格式化
遵循 Vue 官方风格指南
使用语义化的变量和函数命名
代码注释清晰明了

2. 分支管理

master 分支: 主分支，用于发布稳定版本
dev 分支: 开发分支，用于日常开发
feature/* 分支: 功能分支，用于开发新功能
fix/* 分支: 修复分支，用于修复bug

3. 提交规范

提交信息格式

<type>(<scope>): <subject>

<body>

<footer>

提交类型

类型	说明
`feat`	新功能
`fix`	修复bug
`docs`	文档修改
`style`	代码样式修改
`refactor`	代码重构
`perf`	性能优化
`test`	测试相关
`chore`	构建或工具链相关

提交示例

feat(login): 添加验证码登录功能

- 添加验证码输入框
- 集成验证码生成服务
- 添加验证码验证逻辑

Close: #123

🎯 常见问题与解决方案

1. 依赖安装问题

问题: 安装依赖时出现网络错误

解决方案:

bash

# 更换npm镜像
yarn config set registry https://registry.npmmirror.com

# 清除缓存
yarn cache clean

# 重新安装依赖
yarn install

2. 构建失败问题

问题: 构建时出现内存不足错误

解决方案:

bash

# 增加Node.js内存限制
NODE_OPTIONS="--max-old-space-size=4096" yarn build

3. 开发服务器启动失败

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

解决方案:

bash

# 修改开发服务器端口
# 在 vue.config.js 中添加
module.exports = {
  devServer: {
    port: 8081
  }
};

4. 环境变量不生效

问题: 环境变量修改后不生效

解决方案:

bash

# 重启开发服务器
# 或清除浏览器缓存

📊 开发工具链架构

┌─────────────────────────────────────────────────────────┐
│                     开发工具链                          │
├─────────────┬─────────────┬─────────────┬───────────────┤
│  包管理工具  │  构建工具     │  代码质量工具  │  版本管理工具   │
├─────────────┼─────────────┼─────────────┼───────────────┤
│  Yarn       │  Vue CLI     │  ESLint      │  Git          │
│  npm        │  Webpack     │  Prettier    │  git-tag-cli  │
└─────────────┴─────────────┴─────────────┴───────────────┘

工具链流程

开发阶段 - 使用 Vue CLI 和 Webpack 进行开发
代码检查 - 使用 ESLint 和 Prettier 确保代码质量
构建阶段 - 使用 Vue CLI 构建生产版本
版本管理 - 使用 Git 和 git-tag-cli 进行版本管理
部署阶段 - 部署构建产物到服务器

📈 性能优化

1. 构建优化

代码分割

项目使用 Webpack 的代码分割功能，将代码分割为多个 chunk，按需加载。

资源优化

图片压缩和优化
字体资源优化
静态资源CDN

缓存优化

资源文件哈希命名
长效缓存策略

2. 开发优化

热更新

使用 Vue CLI 的热更新功能，提高开发效率。

调试工具

集成 Vue DevTools 和 Chrome DevTools，便于调试和开发。

🎉 最佳实践

使用统一的开发环境 - 确保团队成员使用相同版本的开发工具
遵循代码规范 - 保持代码风格一致
使用语义化版本控制 - 便于版本管理和问题定位
自动化构建流程 - 使用 CI/CD 工具自动化构建和部署
定期更新依赖 - 保持依赖包的安全性和稳定性
编写测试用例 - 确保代码质量和功能正确性
文档化开发流程 - 便于新成员快速上手

📌 总结

本文档详细介绍了 l-pc-front 项目的开发工具、脚本文件、环境配置和构建命令。通过合理使用这些工具和命令，可以提高开发效率，确保代码质量，简化版本管理和部署流程。

核心优势

自动化脚本 - 简化版本管理和构建流程
多环境支持 - 灵活适配不同部署环境
完善的开发工具链 - 提高开发效率和代码质量
清晰的开发流程 - 便于团队协作和项目管理

未来优化方向

集成 CI/CD - 实现自动化构建和部署
增加单元测试和集成测试 - 提高代码质量
优化构建速度 - 减少构建时间
完善监控和日志 - 便于问题定位和性能优化

通过不断优化开发工具和流程，项目将能够更好地支持快速迭代和扩展，提高开发效率和代码质量。

文档维护: l-pc-front 开发组
最后更新: 2025-12-20

🛠️ 开发工具与脚本文档 ​

📋 开发工具概览 ​

核心开发环境 ​

辅助开发工具 ​

📜 脚本文件详解 ​

1. 版本生成脚本 (generate-version.js) ​

2. Git Tag 提交工具 (git-tag-cli.js) ​

⚙️ 环境配置 ​

1. 环境变量文件 ​

主要环境变量文件 ​

环境变量示例 ​

2. 配置文件 ​

构建配置文件 ​

构建配置示例 ​

🚀 构建命令 ​

1. 基础构建命令 ​

2. 开发命令 ​

3. 脚本命令 ​

4. 构建命令详解 ​

yarn serve ​

yarn build ​

yarn build:version ​

yarn tag ​

🔧 开发流程 ​

1. 本地开发 ​

步骤1: 克隆代码 ​

步骤2: 安装依赖 ​

步骤3: 启动开发服务器 ​

步骤4: 访问应用 ​

2. 代码提交 ​

步骤1: 检查代码质量 ​

步骤2: 提交代码 ​

步骤3: 推送代码 ​

3. 版本发布 ​

4. 构建部署 ​

步骤1: 构建生产版本 ​

步骤2: 部署构建产物 ​

📝 开发规范 ​

1. 代码规范 ​

2. 分支管理 ​

3. 提交规范 ​

提交信息格式 ​

提交类型 ​

提交示例 ​

🎯 常见问题与解决方案 ​

1. 依赖安装问题 ​

2. 构建失败问题 ​

3. 开发服务器启动失败 ​

4. 环境变量不生效 ​

📊 开发工具链架构 ​

工具链流程 ​

📈 性能优化 ​

1. 构建优化 ​

代码分割 ​

资源优化 ​

缓存优化 ​

2. 开发优化 ​

热更新 ​

调试工具 ​

🎉 最佳实践 ​

📌 总结 ​

核心优势 ​

未来优化方向 ​

🛠️ 开发工具与脚本文档

📋 开发工具概览

核心开发环境

辅助开发工具

📜 脚本文件详解

1. 版本生成脚本 (`generate-version.js`)

2. Git Tag 提交工具 (`git-tag-cli.js`)

⚙️ 环境配置

1. 环境变量文件

主要环境变量文件

环境变量示例

2. 配置文件

构建配置文件

构建配置示例

🚀 构建命令

1. 基础构建命令

2. 开发命令

3. 脚本命令

4. 构建命令详解

`yarn serve`

`yarn build`

`yarn build:version`

`yarn tag`

🔧 开发流程

1. 本地开发

步骤1: 克隆代码

步骤2: 安装依赖

步骤3: 启动开发服务器

步骤4: 访问应用

2. 代码提交

步骤1: 检查代码质量

步骤2: 提交代码

步骤3: 推送代码

3. 版本发布

4. 构建部署

步骤1: 构建生产版本

步骤2: 部署构建产物

📝 开发规范

1. 代码规范

2. 分支管理

3. 提交规范

提交信息格式

提交类型

提交示例

🎯 常见问题与解决方案

1. 依赖安装问题

2. 构建失败问题

3. 开发服务器启动失败

4. 环境变量不生效

📊 开发工具链架构

工具链流程

📈 性能优化

1. 构建优化

代码分割

资源优化

缓存优化

2. 开发优化

热更新

调试工具

🎉 最佳实践

📌 总结

核心优势

未来优化方向