plugin-build-huipro

HuiPro 1.0 子包构建插件

功能特性

• 🚀 子包构建: 为 HuiPro 1.0 系统构建独立的子包
• 🎨 自定义组件前缀: 支持 HUI 组件库的自定义前缀，避免样式冲突
• 🔧 智能变量替换: 支持代码中多个变量的构建时替换
• 📦 灵活配置管理: 支持自定义window配置变量，控制运行时配置
• 🏷️ 路由前缀: 自动为路由添加前缀，确保路由 name 和 chunkName 唯一性
• 🎯 组件名称注入: 编译时自动为 Vue 组件注入 name 属性，便于调试
• ⚙️ 配置文件支持: 支持在项目配置文件中设置默认选项
• 🛡️ 向后兼容: 完全兼容原有的 LOCAL_CONFIG 替换行为
• 🚫 No-Replace模式: 支持跳过所有变量替换，保持原始变量名

安装

npm install @winner-fed/plugin-build-huipro --save-dev

基本用法

# 基本构建（使用默认配置）
win huipro

# 构建并替换HUI组件前缀
win huipro --prefix win

# 跳过所有变量替换（window配置变量和代码变量都保持原样）
win huipro --no-replace

# 自定义window配置变量（挂载到window上的配置变量）
win huipro --window-config-var MY_CONFIG

# 自定义代码中要替换的变量（逗号分隔）
win huipro --replace-vars "LOCAL_CONFIG,GLOBAL_CONFIG,USER_CONFIG"

# 自定义代码中要替换的变量（JSON格式，支持自定义映射）
win huipro --replace-vars '{"LOCAL_CONFIG": "MY_LOCAL_CONFIG", "GLOBAL_CONFIG": "MY_GLOBAL_CONFIG"}'

# 设置路由前缀（确保路由唯一性）
win huipro --route-prefix admin-common

# 组合使用多个选项
win huipro --prefix win --window-config-var APP_CONFIG --replace-vars "services,api" --route-prefix myapp

配置文件支持

你可以在配置文件中设置默认选项，命令行参数会覆盖配置文件设置：

// .winrc.ts 或 winjs.config.ts
import { defineConfig } from 'win';

export default defineConfig({
  huipro: {
    prefix: 'win',                    // 组件前缀
    noReplace: false,                 // 是否跳过变量替换
    windowConfigVar: 'LOCAL_CONFIG',  // window配置变量名
    replaceVars: 'LOCAL_CONFIG,services', // 代码中要替换的变量
    routePrefix: 'admin-common'       // 路由前缀
  }
});

配置优先级：命令行参数 > 配置文件 > 默认值

核心概念详解

1. Window配置变量 (--window-config-var)

用途: 控制挂载到window上的全局配置变量名

• 默认值: LOCAL_CONFIG
• 生成位置: sysconfig.js 文件
• 命名规则:
  • 正常模式: window.变量名_子包名 = 配置内容
  • No-Replace模式: window.变量名 = 配置内容

# 示例
win huipro --window-config-var APP_CONFIG
# 生成: window.APP_CONFIG_myapp = {...}

win huipro --window-config-var APP_CONFIG --no-replace
# 生成: window.APP_CONFIG = {...}

2. 代码变量替换 (--replace-vars)

用途: 在构建的代码中替换变量引用

• 默认值: LOCAL_CONFIG
• 支持格式: 单个变量、逗号分隔、JSON映射
• 作用范围: 所有构建产物的 JavaScript 文件

3. 路由前缀 (--route-prefix)

用途: 为路由添加唯一前缀，确保多个子包之间路由不冲突

• 默认值: 无（可选参数）
• 命名规则: 必须以字母、下划线或$开头，可以包含字母、数字、下划线、$和连字符
• 作用效果:
  • 为路由的 name 添加前缀
  • 为 webpack chunkName 添加前缀
  • 为 Vue 组件自动注入 name 属性（使用路由 name）

# 示例
win huipro --route-prefix admin-common

# 效果：
# 路由配置：
#   name: 'index' → 'admin-common_index'
#   webpackChunkName: 'views/index' → 'admin-common_index'
# 
# Vue 组件编译后：
#   export default {
#     name: 'admin-common_index',  // 自动注入
#     data() { ... }
#   }

# 单个变量
win huipro --replace-vars API_CONFIG
# 代码中的 API_CONFIG → API_CONFIG_myapp

# 多个变量
win huipro --replace-vars "LOCAL_CONFIG,services,api"
# 代码中的 LOCAL_CONFIG → LOCAL_CONFIG_myapp
# 代码中的 services → services_myapp
# 代码中的 api → api_myapp

# JSON映射（自定义目标名称）
win huipro --replace-vars '{"LOCAL_CONFIG": "APP_CONFIG", "services": "MY_SERVICES"}'
# 代码中的 LOCAL_CONFIG → APP_CONFIG_myapp
# 代码中的 services → MY_SERVICES_myapp

变量替换详解

支持的格式

1. 单个变量

   win huipro --replace-vars MY_CONFIG

2. 逗号分隔的多个变量

   win huipro --replace-vars "LOCAL_CONFIG,GLOBAL_CONFIG,USER_CONFIG"

3. JSON格式（支持自定义映射）

   win huipro --replace-vars '{"LOCAL_CONFIG": "MY_LOCAL_CONFIG", "GLOBAL_CONFIG": "MY_GLOBAL_CONFIG"}'

实际使用示例

假设子包名为 myapp：

# 场景1: 只自定义window配置变量
win huipro --window-config-var MY_CONFIG
# 结果: 
#   - 生成 window.MY_CONFIG_myapp = {...}
#   - 代码中的 LOCAL_CONFIG 会被替换为 LOCAL_CONFIG_myapp

# 场景2: 只自定义代码变量替换
win huipro --replace-vars "API_CONFIG,UI_CONFIG"
# 结果:
#   - 生成 window.LOCAL_CONFIG_myapp = {...}
#   - 代码中的 API_CONFIG → API_CONFIG_myapp
#   - 代码中的 UI_CONFIG → UI_CONFIG_myapp

# 场景3: 两者都自定义
win huipro --window-config-var MY_CONFIG --replace-vars "API_CONFIG,UI_CONFIG"
# 结果:
#   - 生成 window.MY_CONFIG_myapp = {...}
#   - 代码中的 API_CONFIG → API_CONFIG_myapp
#   - 代码中的 UI_CONFIG → UI_CONFIG_myapp

# 场景4: 使用 --no-replace 模式
win huipro --no-replace
# 结果:
#   - 生成 window.LOCAL_CONFIG = {...} (不添加子包名后缀)
#   - 代码中的变量不会被替换，保持原样

# 场景5: --no-replace 与自定义配置变量组合
win huipro --window-config-var MY_CONFIG --no-replace
# 结果:
#   - 生成 window.MY_CONFIG = {...} (不添加子包名后缀)
#   - 代码中的变量不会被替换，保持原样

参数说明

| 参数 | 说明 | 默认值 | 示例 | | ----------------------- | ------------------------------------------------------ | ------------------ | ------------------------------------------ | | --prefix | 自定义HUI组件前缀 | 'we' | --prefix win | | --no-replace | 跳过所有变量替换（window配置变量和代码变量都保持原样） | false | --no-replace | | --window-config-var | 挂载到window上的配置变量名 | 'LOCAL_CONFIG' | --window-config-var MY_CONFIG | | --replace-vars | 代码中要替换的变量 | 'LOCAL_CONFIG' | --replace-vars "LOCAL_CONFIG,services" | | --route-prefix | 路由前缀，确保路由名称和组件名称唯一性 | 无（可选） | --route-prefix admin-common |

最佳实践

1. 变量命名建议

# 推荐：使用语义化的变量名
win huipro --window-config-var APP_CONFIG --replace-vars "services,api,config"

# 推荐：使用JSON格式进行精确映射
win huipro --replace-vars '{"LOCAL_CONFIG": "APP_CONFIG", "services": "API_SERVICES"}'

2. 配置文件使用

// 推荐：在配置文件中设置项目默认值
export default defineConfig({
  huipro: {
    prefix: 'myapp',
    windowConfigVar: 'APP_CONFIG',
    replaceVars: 'LOCAL_CONFIG,services,api',
    routePrefix: 'myapp'  // 为路由添加唯一前缀
  }
});

3. 团队协作

# 在package.json中定义脚本
{
  "scripts": {
    "build:child": "win huipro --route-prefix myapp",
    "build:child:prod": "win huipro --prefix prod --window-config-var PROD_CONFIG --route-prefix myapp-prod",
    "build:child:dev": "win huipro --no-replace --route-prefix myapp-dev"
  }
}

4. 路由前缀的使用场景

# 场景1: 多个子包共存时，避免路由冲突
win huipro --route-prefix user-center
win huipro --route-prefix order-system
win huipro --route-prefix admin-panel

# 场景2: 同一子包的不同环境
win huipro --route-prefix myapp-dev
win huipro --route-prefix myapp-prod

# 场景3: 便于调试和追踪
# 带有 routePrefix 的组件会自动注入 name 属性
# 在 Vue DevTools 中可以清晰看到组件来源

错误处理

插件包含完善的错误处理机制：

• ✅ 变量名验证: 自动验证JavaScript变量名合法性
• ✅ JSON格式验证: 检查JSON格式的正确性
• ✅ 回退机制: 出错时自动回退到默认行为
• ✅ 详细日志: 提供清晰的错误信息和操作日志

路由前缀详解

工作原理

使用 --route-prefix 时，插件会：

1. 修改路由配置

   • 为路由的 name 添加前缀
   • 为 webpackChunkName 添加前缀

2. 自动注入组件 name

   • 在编译时通过 webpack loader 为 Vue 组件注入 name 属性
   • 使用路由的 name 作为组件的 name
   • 支持所有 Vue 组件定义格式

3. 确保唯一性

   • 避免多个子包之间的路由冲突
   • 便于在 Vue DevTools 中识别组件来源
   • 提高调试效率

示例对比

不使用 routePrefix：

// 路由配置
{
  name: 'index',
  path: '/index',
  component: () => import(/* webpackChunkName: "views/index" */ '@/pages/index.vue')
}

// Vue 组件（需要手动定义）
export default {
  // name: 'index',  // 可能缺失或冲突
  data() { ... }
}

使用 routePrefix: 'admin-common'：

// 路由配置（自动添加前缀）
{
  name: 'admin-common_index',
  path: '/index',
  component: () => import(/* webpackChunkName: "admin-common_index" */ '@/pages/index.vue')
}

// Vue 组件（自动注入 name）
export default {
  name: 'admin-common_index',  // ✓ 自动注入，无需手动定义
  data() { ... }
}

常见问题

Q: 如何处理现有项目的迁移？

A: 插件完全向后兼容，现有项目无需修改：

# 现有项目默认行为保持不变
win huipro  # 等同于原来的行为

# 新项目建议添加 routePrefix
win huipro --route-prefix myapp

Q: 如何调试变量替换？

A: 查看构建日志，插件会详细输出所有替换操作：

win huipro --replace-vars "LOCAL_CONFIG,services"
# 输出示例：
# 成功替换了 2 个配置变量:
#   LOCAL_CONFIG → LOCAL_CONFIG_myapp
#   services → services_myapp
# 影响文件数: 15

Q: 什么时候使用 --no-replace？

A: 以下场景建议使用 --no-replace：

• 开发环境调试时
• 与主应用共享配置时
• 不需要变量隔离时

Q: JSON格式的变量映射有什么好处？

A: JSON格式提供更精确的控制：

# 可以将一个变量映射到不同的目标名称
win huipro --replace-vars '{"LOCAL_CONFIG": "MY_APP_CONFIG", "services": "API_SERVICES"}'

Q: 路由前缀支持哪些字符？

A: 路由前缀必须符合以下规则：

• 必须以字母、下划线或 $ 开头
• 可以包含字母、数字、下划线、$ 和连字符（-）
• 不能以连字符开头或结尾
• 长度限制为 1-50 个字符

# ✓ 有效的前缀
win huipro --route-prefix admin
win huipro --route-prefix admin-common
win huipro --route-prefix admin_common
win huipro --route-prefix $admin
win huipro --route-prefix _admin

# ✗ 无效的前缀
win huipro --route-prefix -admin  # 不能以连字符开头
win huipro --route-prefix admin-  # 不能以连字符结尾
win huipro --route-prefix 123admin  # 不能以数字开头

Q: 组件 name 注入是如何工作的？

A: 插件在编译时通过自定义 webpack loader 处理：

1. 在 Vue 文件编译前拦截源码
2. 根据路由配置找到对应的组件 name
3. 在 <script> 块中自动添加或替换 name 属性
4. 支持多种组件定义格式（export default、Vue.extend、defineComponent、script setup）

这个过程是自动的，无需修改源文件，也不会被代码压缩混淆影响。

注意事项

1. 变量命名规范: 配置变量名必须符合JavaScript变量命名规范
2. 保留字限制: 不能使用JavaScript保留字作为变量名
3. 参数优先级: 命令行参数 > 配置文件 > 默认值
4. 向后兼容: 默认不影响原有的 LOCAL_CONFIG 替换行为
5. 职责分离: --window-config-var 只影响生成的配置文件，--replace-vars 只影响代码中的变量替换
6. 全局控制: --no-replace 会同时影响window配置变量和代码变量替换，两者都保持原样不添加子包名后缀
7. 文件范围: 变量替换只作用于 .js 文件，不影响其他类型的文件
8. 路由前缀: 使用 --route-prefix 后需要重新构建项目，确保 loader 正确编译
9. 组件 name: 组件 name 注入仅在使用 --route-prefix 时生效，会自动处理所有路由对应的 Vue 组件

许可证

MIT