GenePlus Front OSS Plugin

一个专为 Webpack 3+ 设计的 OSS 上传插件，支持版本化部署和动态 publicPath 替换。

特性

• ✅ 版本化部署：支持语义化版本号（如 V3.17.22.250730）
• ✅ 动态 publicPath：打包前自动修改 Webpack 的 publicPath 配置
• ✅ HTML 资源更新：自动更新 HTML 文件中的资源引用路径
• ✅ Webpack 兼容性：同时支持 Webpack 3.x、4.x 和 5.x
• ✅ 环境变量配置：通过环境变量配置 OSS 连接信息
• ✅ 保持目录结构：上传时保持原有的 dist 目录结构
• ✅ 并发上传：支持配置并发上传数量提高效率
• ✅ 缓存优化：自动设置 1 年缓存策略

安装

npm install gene-plus-front-oss-plugin --save-dev

# 如果需要使用 .env 文件管理环境变量
npm install dotenv --save-dev

使用方法

1. 基本配置

// webpack.config.js
// 如果使用 .env 文件，需要在顶部加载
require('dotenv').config();

const GenePlusFrontOssPlugin = require('gene-plus-front-oss-plugin');

module.exports = {
  // ... 其他配置
  output: {
    path: __dirname + '/dist',
    filename: 'bundle.js'
  },
  plugins: [
    new GenePlusFrontOssPlugin({
      version: 'V3.17.22.250730', // 必需：手动指定版本号
      publicPathBase: 'https://your-cdn.com/', // CDN 基础路径
      ossConfig: {
        // OSS 配置，也可以通过环境变量设置
        region: process.env.OSS_REGION || 'oss-cn-hangzhou',
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        bucket: process.env.OSS_BUCKET || 'your-bucket'
      },
      enabled: process.env.NODE_ENV === 'production', // 仅在生产环境启用
      include: ['**/*'], // 包含所有文件
      exclude: ['*.map'], // 排除 source map 文件
      dryRun: false, // 设为 true 进行测试运行
      concurrency: 5, // 并发上传数
      logger: console // 日志输出
    })
  ]
};

2. 环境变量配置

创建 .env 文件：

# OSS 配置
OSS_REGION=oss-cn-hangzhou
OSS_ACCESS_KEY_ID=your_access_key_id
OSS_ACCESS_KEY_SECRET=your_access_key_secret
OSS_BUCKET=your-bucket-name

# 部署配置
NODE_ENV=production

3. 版本化部署示例

假设你的版本号是 V3.17.22.250730，插件会：

1. 修改 publicPath：将 Webpack 的 output.publicPath 修改为 https://your-cdn.com/V3.17.22.250730/dist/
2. 上传文件：将所有构建文件上传到 OSS 的 V3.17.22.250730/dist/ 目录下
3. 更新 HTML：自动更新 HTML 文件中的资源引用路径

OSS 目录结构：

your-bucket/
├── V3.17.22.250730/
│     └── dist/
│       ├── index.html
│       ├── static/
│       │   ├── css/
│       │   │    └── main.css
│       │    └── js/
│       │        └── main.js
│         └── assets/
│             └── images/
└── V3.17.21.250729/  # 之前的版本
      └── dist/
          └── ...

配置选项

| 选项 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | version | string | ✅ | - | 版本号，如 V3.17.22.250730 | | publicPathBase | string | ❌ | '' | CDN 基础路径，如 https://your-cdn.com/ | | ossConfig | object | ✅ | - | OSS 配置对象 | | ossConfig.region | string | ✅ | - | OSS 区域 | | ossConfig.accessKeyId | string | ✅ | - | OSS Access Key ID | | ossConfig.accessKeySecret | string | ✅ | - | OSS Access Key Secret | | ossConfig.bucket | string | ✅ | - | OSS Bucket 名称 | | ossConfig.basePath | string | ❌ | '' | OSS 根路径 | | enabled | boolean | ❌ | true | 是否启用插件 | | include | string[] | ❌ | ['**/*'] | 包含的文件模式 | | exclude | string[] | ❌ | [] | 排除的文件模式 | | dryRun | boolean | ❌ | false | 测试运行，不实际上传 | | concurrency | number | ❌ | 4 | 并发上传数量 | | logger | object | ❌ | console | 日志输出对象 |

工作原理

1. 编译前阶段：

   • 检测 Webpack 版本并注册相应钩子
   • 修改 Webpack 的 output.publicPath 为 ${publicPathBase}${version}/dist/

2. 编译后阶段：

   • 处理 HTML 文件，更新其中的资源引用路径
   • 过滤需要上传的文件
   • 批量并发上传文件到 OSS

3. 版本目录结构：

   • OSS 路径格式：${version}/dist/${原始文件路径}
   • 保持原有的 dist 目录结构不变

Webpack 版本兼容性

插件自动检测 Webpack 版本并使用相应的钩子系统：

• Webpack 3.x：使用 compiler.plugin() 方式注册 run 和 emit 钩子

• Webpack 4.x+：使用 compiler.hooks 方式注册 beforeRun 和 afterEmit 钩子

快速开始

// webpack.config.js
require('dotenv').config();

const GenePlusFrontOssPlugin = require('gene-plus-front-oss-plugin');

module.exports = {
  mode: 'production',
  entry: './src/index.js',
  output: {
    path: __dirname + '/dist',
    filename: 'bundle.js'
  },
  plugins: [
    new GenePlusFrontOssPlugin({
      version: 'V3.17.22.250730',
      publicPathBase: 'https://cdn.yourdomain.com/',
      ossConfig: {
        region: process.env.OSS_REGION,
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        bucket: process.env.OSS_BUCKET
      }
    })
  ]
};

故障排除

常见问题

1. 插件不生效

   • 检查 enabled 选项是否设置为 true
   • 验证环境变量 NODE_ENV 是否正确设置

2. 上传失败

   • 确认 OSS 配置参数正确
   • 检查网络连接状态
   • 验证 OSS Bucket 权限

3. HTML 文件资源路径未更新

   • 检查 HTML 文件是否被正确处理
   • 验证正则表达式匹配是否正确

4. OSS 客户端初始化失败

   • 检查 OSS 配置是否完整
   • 验证 Access Key 和 Secret 是否正确

调试模式

new GenePlusFrontOssPlugin({
  // ... 其他配置
  dryRun: true, // 启用测试模式
  concurrency: 1, // 降低并发数便于调试
  logger: {
    log: console.log,
    error: console.error,
    warn: console.warn
  }
});

注意事项

1. 版本号格式：建议使用语义化版本号，如 V3.17.22.250730
2. 环境变量：生产环境中建议通过环境变量配置敏感信息
3. 并发控制：可根据网络状况调整 concurrency 参数
4. Webpack 兼容性：插件自动适配 Webpack 3.x、4.x 和 5.x
5. 测试运行：首次部署前建议设置 dryRun: true 验证配置
6. 缓存策略：上传文件时自动设置 1 年缓存

许可证

MIT