@taro-minify-pack/helper 0.1.4-alpha.3 → 0.1.4-alpha.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +149 -197
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,239 +1,191 @@
1
- ## @taro-minify-pack/preset
1
+ # @taro-minify-pack/helper
2
2
 
3
- > 预设配置，整合了 @taro-minify-pack 系列核心插件，提供一键式优化解决方案，简化 Taro 项目的性能优化配置。
3
+ > @taro-minify-pack 系列插件的公共工具库，提供资源上传、上传适配器定义等通用能力。
4
4
 
5
- 该预设包含以下插件：
6
-
7
- - `@taro-minify-pack/plugin-async-pack`: 异步加载主包代码，优化主包体积
8
- - `@taro-minify-pack/plugin-remote-assets`: 远程资源上传，优化主包体积
9
- - `@taro-minify-pack/plugin-cover-browserslist`: 根据微信小程序基础库版本自动设置 browserslist
10
- - `@taro-minify-pack/plugin-bundle-analyzer`: 包体积分析工具
5
+ 该包为系列插件提供底层支持，主要包含资源上传核心逻辑、上传适配器定义工具以及内置的阿里云 OSS 上传适配器，供 `@taro-minify-pack/plugin-remote-assets`、`@taro-minify-pack/plugin-bundle-stats` 等插件复用。
11
6
 
12
7
  ## ✨ 功能特性
13
8
 
14
- | 插件名称 | 功能描述 |
15
- |---------------------------------------------|-----------------------------------------------|
16
- | @taro-minify-pack/plugin-async-pack | 实现主包代码的异步加载，显著减小主包体积，提升小程序启动性能 |
17
- | @taro-minify-pack/plugin-remote-assets | 将静态资源上传到远程 CDN，减少主包大小，加快资源加载速度 |
18
- | @taro-minify-pack/plugin-cover-browserslist | 根据微信小程序基础库版本自动设置 browserslist，减少不必要的 polyfill |
19
- | @taro-minify-pack/plugin-bundle-analyzer | 可视化分析包体积，帮助识别体积过大的模块和依赖 |
9
+ * 📤 资源并发上传，基于 PromisePool 控制并发数
10
+ * 🧩 上传适配器定义工具（`defineUploaderAdapter`），支持类型安全地自定义适配器
11
+ * ☁️ 内置阿里云 OSS 上传适配器，开箱即用
12
+ * 🔑 基于文件内容 MD5 的资源唯一性校验
13
+ * 📁 递归目录文件遍历工具
20
14
 
21
15
  ## 📦 安装
22
16
 
23
- ```bash
24
- # 使用 npm
25
- npm install @taro-minify-pack/preset
17
+ ### npm
18
+
19
+ ```sh
20
+ npm install @taro-minify-pack/helper
21
+ ```
26
22
 
27
- # 使用 yarn
28
- yarn add @taro-minify-pack/preset
23
+ ### yarn
29
24
 
30
- # 使用 pnpm
31
- pnpm add @taro-minify-pack/preset
25
+ ```sh
26
+ yarn add @taro-minify-pack/helper
32
27
  ```
33
28
 
34
- ## 🛠️ 配置
29
+ ### pnpm
30
+
31
+ ```sh
32
+ pnpm add @taro-minify-pack/helper
33
+ ```
35
34
 
36
- ### Babel 配置
35
+ ## 🔧 API
36
+
37
+ ### `uploadAssets(opt)`
38
+
39
+ 扫描指定目录下的所有文件，并发上传至远程存储服务。
37
40
 
38
41
  ```ts
39
- // babel-preset-taro 更多选项和默认值：
40
- // https://docs.taro.zone/docs/next/babel-config
41
- module.exports = {
42
- presets: [
43
- ['taro', {
44
- framework: 'react',
45
- ts: true,
46
- compiler: 'webpack5',
47
- // 在原有基础上添加这个配置即可
48
- 'dynamic-import-node': process.env.TARO_ENV !== 'weapp',
49
- }]
50
- ]
51
- }
42
+ import { uploadAssets } from '@taro-minify-pack/helper'
43
+
44
+ const results = await uploadAssets({
45
+ assetsDirPath: '/path/to/assets',
46
+ upload: async (localAssetInfo) => {
47
+ // 实现上传逻辑，返回包含 remoteUrl 的资源信息
48
+ return { ...localAssetInfo, remoteUrl: 'https://example.com/asset.png' }
49
+ },
50
+ payload: {}, // 可选，透传给 upload 函数的额外参数
51
+ processAssets: (assets) => assets, // 可选，上传前对资源列表进行过滤或排序
52
+ })
52
53
  ```
53
54
 
54
- ### Taro 配置
55
-
56
- #### 基础配置示例
57
-
58
- ```js
59
- // config/index.js
60
- const path = require('path')
61
- const {aliOssUploadAdapter} = require('@taro-minify-pack/preset')
62
-
63
- module.exports = {
64
- compiler: {
65
- type: 'webpack5',
66
- prebundle: {
67
- // 关闭预打包，与分包异步编译有冲突
68
- enable: false,
69
- }
70
- },
71
- presets: [
72
- ['@taro-minify-pack/preset', {
73
- // 开启远程资源上传，优化主包体积
74
- remoteAssets: {
75
- pathAlias: {
76
- '@': path.resolve(__dirname, '../src/'),
77
- '~@': path.resolve(__dirname, '../src/'),
78
- },
79
- assetsDirPath: path.resolve(__dirname, '../src/assets/'),
80
- uploader: aliOssUploadAdapter({
81
- customDomain: 'https://your-custom-domain.com',
82
- accessKeyId: 'your-access-key-id',
83
- accessKeySecret: 'your-access-key-secret',
84
- bucket: 'your-bucket-name',
85
- bucketDir: 'bucketDir',
86
- region: 'your-region',
87
- })
88
- },
89
- // 自动设置 browserslist 配置
90
- coverBrowsersList: {
91
- // 必填：微信小程序基础库最低版本号
92
- minBaseLibraryVersion: '2.14.4'
93
- },
94
- // 包体积分析配置
95
- bundleAnalyzer: true,
96
- // 开启异步加载主包代码，优化主包体积
97
- asyncPack: true
98
- }],
99
- ],
100
- };
55
+ #### 参数说明
56
+
57
+ | 参数名 | 是否必填 | 类型 | 默认值 | 说明 |
58
+ |-----------------|------|------------------------------|----------------------|------------------------|
59
+ | `assetsDirPath` | 是 | `string` | - | 本地静态资源根目录 |
60
+ | `upload` | 是 | `Uploader` | - | 上传函数，接收资源信息并返回远程 URL |
61
+ | `payload` | 否 | `any` | - | 透传给 upload 函数的额外参数 |
62
+ | `processAssets` | 否 | `(assets) => assets` | `(assets) => assets` | 上传前对资源列表进行过滤或排序 |
63
+
64
+ ### `defineUploaderAdapter(adapter)`
65
+
66
+ 定义上传适配器的工具函数，提供类型推导支持。
67
+
68
+ ```ts
69
+ import { defineUploaderAdapter } from '@taro-minify-pack/helper'
70
+
71
+ interface MyAdapterOpt {
72
+ endpoint: string
73
+ apiKey: string
74
+ }
75
+
76
+ const myUploadAdapter = defineUploaderAdapter((opt: MyAdapterOpt) => {
77
+ return async (localAssetInfo, payload) => {
78
+ // 实现上传逻辑
79
+ const remoteUrl = await uploadToMyService(opt, localAssetInfo)
80
+ return { ...localAssetInfo, remoteUrl }
81
+ }
82
+ })
101
83
  ```
102
84
 
103
- #### 完整配置示例
104
-
105
- ```js
106
- // config/index.js
107
- const path = require('path')
108
- const {aliOssUploadAdapter} = require('@taro-minify-pack/remote-assets-adapter-ali-oss')
109
-
110
- module.exports = {
111
- compiler: {
112
- type: 'webpack5',
113
- prebundle: {
114
- // 关闭预打包，与分包异步编译有冲突
115
- enable: false,
116
- }
117
- },
118
- presets: [
119
- ['@taro-minify-pack/preset', {
120
- // 远程资源上传配置
121
- remoteAssets: {
122
- pathAlias: {
123
- '@': path.resolve(__dirname, '../src/'),
124
- '~@': path.resolve(__dirname, '../src/'),
125
- },
126
- assetsDirPath: path.resolve(__dirname, '../src/assets/'),
127
- uploader: aliOssUploadAdapter({
128
- customDomain: 'https://your-custom-domain.com',
129
- accessKeyId: 'your-access-key-id',
130
- accessKeySecret: 'your-access-key-secret',
131
- bucket: 'your-bucket-name',
132
- bucketDir: 'bucketDir',
133
- region: 'your-region',
134
- })
135
- },
136
- // 异步加载主包代码配置
137
- asyncPack: {
138
- // 动态包名称前缀
139
- dynamicPackageNamePrefix: 'dynamic-package',
140
- // 动态包数量
141
- dynamicPackageCount: 1,
142
- // 自定义异步分包
143
- customDynamicPackages: [
144
- {
145
- name: 'sync-style',
146
- test: (module) => /src[\\/]pages[\\/]sync-style[\\/]/.test(module.identifier()),
147
- },
148
- {
149
- name: 'async-style',
150
- test: (module) => /src[\\/]pages[\\/]async-style[\\/]/.test(module.identifier()),
151
- asyncStyle: true
152
- }
153
- ]
154
- },
155
- // 自动设置 browserslist 配置
156
- coverBrowsersList: {
157
- // 必填：微信小程序基础库最低版本号
158
- minBaseLibraryVersion: '2.14.4'
159
- },
160
- // 包体积分析配置
161
- bundleAnalyzer: {
162
- // 服务器主机
163
- analyzerHost: '127.0.0.1',
164
- // 服务器端口
165
- analyzerPort: 8888,
166
- // 是否自动打开报告
167
- openAnalyzer: true
168
- }
169
- }],
170
- ],
171
- };
85
+ ### `aliOssUploadAdapter(opt)`
86
+
87
+ 内置的阿里云 OSS 上传适配器，支持自定义域名、文件名生成、目录前缀等配置。
88
+
89
+ ```ts
90
+ import { aliOssUploadAdapter } from '@taro-minify-pack/helper'
91
+
92
+ const uploader = aliOssUploadAdapter({
93
+ accessKeyId: 'your-access-key-id',
94
+ accessKeySecret: 'your-access-key-secret',
95
+ bucket: 'your-bucket-name',
96
+ region: 'oss-cn-hangzhou',
97
+ bucketDir: 'taro-assets', // 可选，OSS 存储目录前缀，默认为根目录
98
+ customDomain: 'https://cdn.example.com', // 可选，自定义域名
99
+ fileName: (info) => info.uniqueKey, // 可选，远程文件名生成函数，默认使用 uniqueKey
100
+ })
172
101
  ```
173
102
 
174
- ## 📋 配置选项
103
+ #### AliOssUploadAdapterOpt 参数说明
104
+
105
+ | 参数名 | 是否必填 | 类型 | 默认值 | 说明 |
106
+ |------------------|------|--------------------------------------|-------------------------|--------------------------|
107
+ | `accessKeyId` | 是 | `string` | - | 阿里云 AccessKey ID |
108
+ | `accessKeySecret`| 是 | `string` | - | 阿里云 AccessKey Secret |
109
+ | `bucket` | 是 | `string` | - | OSS Bucket 名称 |
110
+ | `region` | 是 | `string` | - | OSS 区域 |
111
+ | `bucketDir` | 否 | `string` | `''` | OSS 存储目录前缀 |
112
+ | `customDomain` | 否 | `string` | - | 自定义域名，设置后远程 URL 使用该域名 |
113
+ | `fileName` | 否 | `(info) => string` | `(info) => info.uniqueKey` | 远程文件名生成函数 |
114
+
115
+ ### 工具函数
175
116
 
176
- ### 通用配置
117
+ #### `travelFiles(dir)`
177
118
 
178
- | 选项名 | 类型 | 默认值 | 描述 |
179
- |-------------------|----------------------------------|---------|-----------------------------|
180
- | asyncPack | `boolean` \| `AsyncPackOpts` | `false` | 异步加载主包代码配置，设为 `true` 使用默认配置 |
181
- | remoteAssets | `RemoteAssetPluginOpt` | - | 远程资源上传配置 |
182
- | coverBrowsersList | `CoverBrowsersListOpt` | - | 自动设置 browserslist 配置 |
183
- | bundleAnalyzer | `boolean` \| `BundleAnalyzerOpt` | `false` | 包体积分析配置，设为 `true` 使用默认配置 |
119
+ 递归遍历目录，返回所有文件的绝对路径列表。
120
+
121
+ ```ts
122
+ import { travelFiles } from '@taro-minify-pack/helper'
123
+
124
+ const files = travelFiles('/path/to/directory')
125
+ // => ['/path/to/directory/a.png', '/path/to/directory/sub/b.png']
126
+ ```
184
127
 
185
- ### asyncPack 配置
128
+ #### `generateFileUniqueKey(filePath)`
186
129
 
187
- | 选项名 | 类型 | 默认值 | 描述 |
188
- |--------------------------|--------------------------|---------------------|-----------|
189
- | dynamicPackageNamePrefix | `string` | `'dynamic-package'` | 动态包名称前缀 |
190
- | dynamicPackageCount | `number` | `1` | 动态包数量 |
191
- | customDynamicPackages | `CustomDynamicPackage[]` | `[]` | 自定义异步分包配置 |
130
+ 基于文件内容生成 MD5 唯一标识。
192
131
 
193
- ### remoteAssets 配置
132
+ ```ts
133
+ import { generateFileUniqueKey } from '@taro-minify-pack/helper'
194
134
 
195
- | 选项名 | 类型 | 默认值 | 描述 |
196
- |---------------|--------------------------|-----|--------------|
197
- | assetsDirPath | `string` | - | 静态资源目录路径（必填） |
198
- | pathAlias | `Record<string, string>` | - | 路径别名配置 |
199
- | uploader | `Function` | - | 资源上传适配器函数 |
135
+ const key = generateFileUniqueKey('/path/to/file.png')
136
+ // => '2f9b7a8c9d0e1f2a3b4c5d6e7f8a9b0c'
137
+ ```
200
138
 
201
- ### coverBrowsersList 配置
139
+ ### 类型定义
202
140
 
203
- | 选项名 | 类型 | 默认值 | 描述 |
204
- |-----------------------|----------|-----|-------------------|
205
- | minBaseLibraryVersion | `string` | - | 微信小程序基础库最低版本号（必填） |
141
+ ```ts
142
+ interface LocalAssetInfo {
143
+ localPath: string // 本地资源文件路径
144
+ fileName: string // 文件名（不含扩展名）
145
+ uniqueKey: string // 基于文件内容生成的 MD5 值
146
+ ext: string // 文件扩展名（含 .）
147
+ }
206
148
 
207
- ### bundleAnalyzer 配置
149
+ interface RemoteAssetInfo {
150
+ ext: string // 文件扩展名
151
+ localPath: string // 本地资源文件路径
152
+ uniqueKey: string // 基于文件内容生成的 MD5 值
153
+ remoteUrl: string // 远程资源访问 URL
154
+ }
208
155
 
209
- | 选项名 | 类型 | 默认值 | 描述 |
210
- |--------------|----------------------|---------------|----------|
211
- | analyzerHost | `string` | `'127.0.0.1'` | 服务器主机 |
212
- | analyzerPort | `number` \| `'auto'` | `8888` | 服务器端口 |
213
- | openAnalyzer | `boolean` | `true` | 是否自动打开报告 |
156
+ type Uploader = (localAssetInfo: LocalAssetInfo, payload?: any) => Promise<RemoteAssetInfo>
214
157
 
215
- ## 🎯 使用场景
158
+ type UploaderAdapter<T = any> = (opt: T) => Uploader
159
+ ```
216
160
 
217
- * 需要快速优化 Taro 项目性能的场景
218
- * 希望简化多插件配置的项目
219
- * 需要同时使用多个 @taro-minify-pack 系列插件的项目
220
- * 对小程序主包体积有严格要求的项目
161
+ ## 🧠 工作原理
221
162
 
222
- ## ⚠️ 注意事项
163
+ 1. **文件扫描**：`travelFiles` 递归遍历指定目录，收集所有文件路径
164
+ 2. **唯一性校验**：`generateFileUniqueKey` 读取文件内容并生成 MD5 值，确保同一内容不会重复上传
165
+ 3. **并发上传**：`uploadAssets` 使用 `@supercharge/promise-pool` 控制并发数（默认为 2），批量上传资源
166
+ 4. **适配器模式**：通过 `defineUploaderAdapter` 定义上传适配器，将上传逻辑与存储服务解耦，支持灵活扩展
223
167
 
224
- 1. **预打包冲突**：当启用 `asyncPack` 时，必须关闭 Taro 的预打包功能（`compiler.prebundle.enable = false`），否则会导致构建冲突。
168
+ ### 阿里云 OSS 适配器工作流程
225
169
 
226
- 2. **Babel 配置**：必须在 Babel 配置中添加 `'dynamic-import-node': process.env.TARO_ENV !== 'weapp'`，以确保异步加载功能在不同环境下正常工作。
170
+ 1. 初始化 OSS 客户端
171
+ 2. 对每个资源文件，先通过 `head` 接口检查远程是否已存在同名文件
172
+ 3. 若已存在，直接返回远程 URL，跳过上传
173
+ 4. 若不存在，调用 `put` 接口上传文件，并返回远程 URL
174
+ 5. 如果配置了 `customDomain`，远程 URL 使用自定义域名；否则使用 OSS 签名 URL
227
175
 
228
- 3. **远程资源上传**：使用 `remoteAssets` 时，需要提供有效的上传适配器和配置信息，确保资源能够正确上传到远程服务器。
176
+ ## 📌 适用场景
229
177
 
230
- 4. **基础库版本**：使用 `coverBrowsersList` 时，必须指定正确的微信小程序基础库版本，以确保生成的代码兼容目标环境。
178
+ * 为 `@taro-minify-pack` 系列插件提供上传能力
179
+ * 需要在 Taro 项目中将静态资源上传至对象存储
180
+ * 需要自定义上传适配器对接不同的存储服务
181
+ * 需要基于文件内容 MD5 进行资源去重
231
182
 
232
- 5. **Webpack 版本**：该预设仅支持 Webpack 5 编译器，请确保 Taro 项目使用 `compiler.type = 'webpack5'`。
183
+ ## ⚠️ 注意事项
233
184
 
234
- 6. **remote-assets 插件版本兼容性**：
235
- - **Taro < 4.0.10**：由于 `@tarojs/webpack5-runner` 不支持使用绝对路径注册 PostCSS 插件，在低版本 Taro 中直接使用本插件可能会导致插件无法生效。如需在低版本中使用，请参考官方 Pull Request( `https://github.com/NervJS/taro/pull/18683/files` ) 自行 patch。
236
- - **Taro ≥ 4.0.10**：可直接使用，无需额外处理。
185
+ 1. **内部依赖**：该包主要为 `@taro-minify-pack` 系列插件提供公共能力，一般不单独使用
186
+ 2. **并发控制**：`uploadAssets` 默认并发数为 2，避免对存储服务造成过大压力
187
+ 3. **文件唯一性**：基于文件内容 MD5 生成唯一标识，仅修改文件名不会触发重新上传
188
+ 4. **OSS 适配器**：使用 `aliOssUploadAdapter` 需要确保阿里云 OSS 配置正确，且有足够的访问权限
237
189
 
238
190
  ## 📄 许可证
239
191
 
@@ -243,4 +195,4 @@ MIT License
243
195
 
244
196
  欢迎提交 Issues 和 Pull Requests！
245
197
 
246
- > 该预设是 @taro-minify-pack 系列插件的一部分，致力于提供完整的 Taro 项目优化解决方案。
198
+ > 该包是 @taro-minify-pack 系列插件的一部分，致力于提供完整的 Taro 项目优化解决方案。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@taro-minify-pack/helper",
3
- "version": "0.1.4-alpha.3",
3
+ "version": "0.1.4-alpha.4",
4
4
  "description": "",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",