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 年缓存策略

安装

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

如果需要使用 .env 文件管理环境变量


npm install dotenv --save-dev
`

使用方法

$3

`javascript
// 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 // 日志输出
})
]
};
`

$3

创建 .env 文件：

`bash


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 钩子

快速开始

`javascript
// 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
}
})
]
};
`

故障排除

$3

1. 插件不生效
- 检查 enabled 选项是否设置为 true
- 验证环境变量 NODE_ENV 是否正确设置

2. 上传失败
- 确认 OSS 配置参数正确
- 检查网络连接状态
- 验证 OSS Bucket 权限

3. HTML 文件资源路径未更新
- 检查 HTML 文件是否被正确处理
- 验证正则表达式匹配是否正确

4. OSS 客户端初始化失败
- 检查 OSS 配置是否完整
- 验证 Access Key 和 Secret 是否正确

$3

`javascript
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