1. 为什么需要从HBuilderX迁移到CLI项目

去年接手公司一个uni-app项目时，我遇到了一个典型痛点：每次发布新版本都需要手动打开HBuilderX，点击菜单选择不同客户的不同平台进行打包。当客户数量增加到5个，平台覆盖微信、支付宝、H5三端时，每次发布都变成了耗时30分钟以上的重复劳动。更糟的是，有次深夜紧急修复bug后，困倦中选错了客户配置，导致生产环境出现了错误版本。

这种场景正是CLI（命令行界面）可以完美解决的。通过命令行工具，我们可以实现：

• 一键完成所有客户所有平台的构建发布
• 将打包流程集成到Jenkins等CI/CD系统中
• 避免人工操作带来的失误风险
• 显著提升多环境发布的效率

2. 项目改造前的准备工作

2.1 环境与工具检查清单

在开始改造前，确保你的开发环境已准备好以下工具：

# 检查Node.js版本（建议14.x以上） node -v # 检查npm/yarn版本 npm -v yarn -v # 全局安装vue-cli（Vue2项目使用3.x版本） npm install -g @vue/cli@3

2.2 现有项目结构分析

典型的HBuilderX创建的uni-app项目目录结构如下：

project-root/ ├── components/ # 公共组件 ├── pages/ # 页面目录 ├── static/ # 静态资源 ├── manifest.json # 应用配置 ├── pages.json # 页面路由配置 └── main.js # Vue入口文件

需要特别注意HBuilderX特有的文件：

• project.config.json- HBuilderX项目配置文件
• unpackage/- 编译输出目录（建议.gitignore忽略）

2.3 创建CLI项目骨架

使用vue-cli初始化新项目：

vue create -p dcloudio/uni-preset-vue my-project-cli

选择模板时注意：

• Vue2项目选择"默认模板(TypeScript)"或"默认模板"
• 不要选择Vue3模板（除非明确要升级）

初始化完成后，将原项目的以下文件/目录复制到新项目中：

• components/
• pages/
• static/
• App.vue
• main.js
• manifest.json
• pages.json

3. 关键配置迁移与改造

3.1 package.json配置调整

CLI项目的核心是package.json中的scripts配置。以下是多平台构建的典型配置：

{ "scripts": { "serve": "npm run dev:h5", "build": "npm run build:h5", "dev:h5": "cross-env NODE_ENV=development UNI_PLATFORM=h5 vue-cli-service uni-build --watch", "build:h5": "cross-env NODE_ENV=production UNI_PLATFORM=h5 vue-cli-service uni-build", "dev:mp-weixin": "cross-env NODE_ENV=development UNI_PLATFORM=mp-weixin vue-cli-service uni-build --watch", "build:mp-weixin": "cross-env NODE_ENV=production UNI_PLATFORM=mp-weixin vue-cli-service uni-build", "dev:mp-alipay": "cross-env NODE_ENV=development UNI_PLATFORM=mp-alipay vue-cli-service uni-build --watch", "build:mp-alipay": "cross-env NODE_ENV=production UNI_PLATFORM=mp-alipay vue-cli-service uni-build" }, "dependencies": { "@dcloudio/uni-app": "^2.0.0", "@dcloudio/uni-mp-weixin": "^2.0.0", "vue": "^2.6.11", "vuex": "^3.4.0" }, "devDependencies": { "@dcloudio/types": "^2.0.0", "@dcloudio/uni-helper-json": "^1.0.5", "@dcloudio/vue-cli-plugin-uni": "^2.0.0", "cross-env": "^7.0.3", "sass": "^1.26.10", "sass-loader": "^8.0.2" } }

3.2 多环境配置方案

针对不同客户环境，推荐使用.env文件管理配置：

.env.client1 # 客户1基础配置 .env.client1.prod # 客户1生产环境 .env.client2 # 客户2基础配置

示例.env文件内容：

# 客户A的微信小程序配置 VUE_APP_CLIENT=clientA VUE_APP_PLATFORM=wechat UNI_APPID=wx1234567890abcdef UNI_APP_NAME=客户A小程序

在代码中通过process.env.VUE_APP_CLIENT访问这些变量。

3.3 条件编译的自动化处理

uni-app的条件编译通常通过注释实现：

// #ifdef H5 console.log('只在H5平台出现'); // #endif

在CLI项目中，可以通过在命令中指定UNI_PLATFORM参数自动处理这些条件编译：

UNI_PLATFORM=mp-weixin npm run build:mp-weixin

4. 实现多客户多平台自动化发布

4.1 基础构建脚本

创建build.js实现核心构建逻辑：

const { execSync } = require('child_process'); const clients = ['clientA', 'clientB', 'clientC']; const platforms = ['h5', 'mp-weixin', 'mp-alipay']; clients.forEach(client => { platforms.forEach(platform => { console.log(`Building ${client} for ${platform}...`); try { execSync(`cross-env VUE_APP_CLIENT=${client} UNI_PLATFORM=${platform} npm run build:${platform}`, { stdio: 'inherit' }); console.log(`Build succeeded for ${client}/${platform}`); } catch (error) { console.error(`Build failed for ${client}/${platform}:`, error); process.exit(1); } }); });

4.2 平台特定处理逻辑

不同平台可能需要特殊处理：

// 微信小程序需要处理project.config.json if (platform === 'mp-weixin') { const projectConfig = { appid: process.env.UNI_APPID, projectname: `${client}-小程序`, // 其他微信特有配置 }; fs.writeFileSync('dist/mp-weixin/project.config.json', JSON.stringify(projectConfig, null, 2)); } // H5平台可能需要部署到不同目录 if (platform === 'h5') { const distPath = `dist/${client}/h5`; if (!fs.existsSync(distPath)) { fs.mkdirSync(distPath, { recursive: true }); } fs.renameSync('dist/h5', distPath); }

4.3 完整的CI/CD集成示例

以下是GitLab CI的配置示例：

stages: - build - deploy build_job: stage: build image: node:14 script: - npm install - node build.js artifacts: paths: - dist/ expire_in: 1 week deploy_h5: stage: deploy image: alpine needs: ["build_job"] script: - apk add rsync openssh - rsync -avz dist/clientA/h5/ user@server:/var/www/clientA/ - rsync -avz dist/clientB/h5/ user@server:/var/www/clientB/ deploy_wechat: stage: deploy image: alpine needs: ["build_job"] script: - apk add curl - for file in dist/*/mp-weixin; do client=${file#dist/} client=${client%/mp-weixin} curl -F "file=@$file" https://api.weixin.qq.com/wxa/upload?access_token=TOKEN done

5. 迁移过程中的常见问题与解决方案

5.1 路径引用问题

HBuilderX对静态资源路径处理比较宽松，而CLI项目需要更规范的引用方式：

// 错误 - HBuilderX可能允许 import util from '../../common/util.js'; // 正确 - CLI项目推荐使用@别名 import util from '@/common/util.js';

在vue.config.js中配置别名：

const path = require('path'); module.exports = { configureWebpack: { resolve: { alias: { '@': path.resolve(__dirname, 'src') } } } };

5.2 CSS预处理器兼容性

如果原项目使用了Sass/Less，需要显式安装对应loader：

npm install -D sass sass-loader

并在所有Vue文件的style标签中声明语言：

<style lang="scss"> /* scss代码 */ </style>

5.3 原生插件兼容性处理

对于使用uni-app原生插件的项目：

1. 将插件从nativeplugins目录复制到新项目
2. 在manifest.json中正确声明插件
3. 运行以下命令安装原生依赖：

npm run postinstall

5.4 性能优化建议

CLI项目构建时可以启用更多优化：

// vue.config.js module.exports = { chainWebpack(config) { // 开启图片压缩 config.module .rule('images') .use('image-webpack-loader') .loader('image-webpack-loader') .options({ bypassOnDebug: true }); // 分包优化 config.optimization.splitChunks({ chunks: 'all', maxSize: 244 * 1024 // 244KB }); } };

6. 进阶：多客户管理的工程化方案

6.1 动态manifest配置

通过JavaScript动态生成manifest.json：

// manifest.config.js module.exports = (client) => { const base = require('./manifest.base.json'); const clients = { clientA: { name: '客户A应用', appid: 'wx123456' }, clientB: { name: '客户B应用', appid: 'wx654321' } }; return { ...base, ...clients[client], // 其他动态配置 }; };

在构建脚本中使用：

const manifest = require('./manifest.config')(process.env.VUE_APP_CLIENT); fs.writeFileSync('src/manifest.json', JSON.stringify(manifest, null, 2));

6.2 自动化版本管理

在package.json中添加自动版本管理脚本：

{ "scripts": { "version": "node version.js", "postversion": "git push --follow-tags" } }

version.js示例：

const fs = require('fs'); const { execSync } = require('child_process'); // 获取当前版本并递增 const pkg = JSON.parse(fs.readFileSync('package.json')); const [major, minor, patch] = pkg.version.split('.').map(Number); pkg.version = `${major}.${minor}.${patch + 1}`; fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2)); // 更新所有客户的版本信息 const clients = ['clientA', 'clientB']; clients.forEach(client => { const manifestPath = `src/manifest-${client}.json`; const manifest = JSON.parse(fs.readFileSync(manifestPath)); manifest.versionName = pkg.version; manifest.versionCode = Date.now(); fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2)); }); execSync('git add package.json src/manifest-*.json');

6.3 构建缓存优化

通过配置cache-loader加速重复构建：

// vue.config.js module.exports = { chainWebpack(config) { config.module .rule('js') .use('cache-loader') .loader('cache-loader') .options({ cacheDirectory: path.resolve(__dirname, '.cache') }); } };

7. 实测效果与性能对比

在我们实际项目中，改造前后的效率对比：

内存占用方面，CLI项目在开发模式下约占用800MB内存，生产构建时峰值达到1.5GB。建议CI服务器至少配置4GB以上内存。

构建速度优化前后对比：

# 优化前 初次构建: 3分12秒 增量构建: 1分45秒 # 优化后（启用缓存、并行等） 初次构建: 1分58秒 增量构建: 38秒

8. 项目改造后的维护建议

1. 依赖管理：

   • 定期运行npm outdated检查更新
   • 锁定核心依赖版本（如uni-app相关包）
   • 使用npm audit检查安全漏洞

2. 构建监控：

   # 记录每次构建的指标 npm run build -- --report

3. 文档维护：

   • 在项目根目录添加BUILD.md记录构建流程
   • 使用JSDoc为构建脚本添加注释
   • 维护客户特定的配置说明

4. 应急方案：

   • 保留HBuilderX项目作为备用
   • 编写回滚脚本
   • 关键发布前手动验证各平台

在实际使用中，我发现CLI项目最大的优势是能够将构建逻辑代码化。曾经遇到过微信小程序审核规则变更导致构建失败的情况，通过git历史快速定位了问题点，并在一小时内为所有客户完成了修复和重新发布，这在原来的HBuilderX工作流中是不可想象的效率提升。