@taro-minify-pack/plugin-remote-assets 0.0.5-alpha.4 → 0.0.5-alpha.6

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 (6) hide show
  1. package/README.md +227 -32
  2. package/dist/index.d.ts +1 -1
  3. package/dist/index.js +1 -0
  4. package/dist/index.js.map +1 -1
  5. package/package.json +1 -1
  6. package/src/index.ts +1 -1
package/README.md CHANGED
@@ -1,48 +1,243 @@
1
- ## @taro-minify-pack/plugin-remote-assets
2
- > 自动上传资源文件并替换路径
3
- >
4
- > 注：`Taro`版本低于`4.0.10`由于`@tarojs/webpack5-runner`不支持绝对路径注册`postcss`插件注册注册,需要参考[pullRequest](https://github.com/NervJS/taro/pull/18683/files)自行 patch
1
+ # @taro-minify-pack/plugin-remote-assets
5
2
 
3
+ > 自动上传本地静态资源并替换为远程访问地址，减少小程序主包体积。
6
4
 
7
- ### 安装
5
+ 该插件会在构建阶段扫描代码与样式中的本地资源引用（如图片、字体等），
6
+ 将其上传至指定的对象存储服务，并将原有本地路径自动替换为远程 URL，
7
+ 从而避免静态资源被打入主包。
8
8
 
9
- ```bash
9
+ ## ⚠️ 版本说明
10
+
11
+ ### Taro < 4.0.10
12
+
13
+ 由于 @tarojs/webpack5-runner 不支持使用绝对路径注册 PostCSS 插件，
14
+ 在低版本 Taro 中直接使用本插件可能会导致插件无法生效。
15
+ 如需在低版本中使用，请参考官方 Pull Request([#18683](https://github.com/NervJS/taro/pull/18683/files)) 自行 patch
16
+
17
+ ### Taro ≥ 4.0.10
18
+
19
+ 可直接使用，无需额外处理。
20
+
21
+ ## ✨ 功能特性
22
+
23
+ * 🚀 构建阶段自动上传本地静态资源
24
+ * 🔁 自动替换 JS / CSS 中的资源引用路径
25
+ * 🧩 支持路径别名解析（@、~@ 等）
26
+ * ☁️ 支持自定义上传适配器
27
+ * 📦 有效降低小程序主包体积
28
+ * 📝 基于文件内容 MD5 的资源唯一性校验
29
+ * 📎 智能缓存机制，避免重复上传
30
+ * ⚡ 并发上传支持，提高构建效率
31
+
32
+ ## 📦 安装
33
+
34
+ ### npm
35
+
36
+ ```sh
10
37
  npm install @taro-minify-pack/plugin-remote-assets
11
38
  ```
12
- #### yarn 安装
13
- ```bash
39
+
40
+ ### yarn
41
+
42
+ ```sh
14
43
  yarn add @taro-minify-pack/plugin-remote-assets
15
44
  ```
16
45
 
17
- #### pnpm 安装
18
- ```bash
46
+ ### pnpm
47
+
48
+ ```sh
19
49
  pnpm add @taro-minify-pack/plugin-remote-assets
20
50
  ```
21
51
 
22
- ### 配置
52
+ ## 🔧 使用配置
53
+
54
+ ### 插件参数说明
55
+
56
+ | 参数名 | 是否必填 | 类型 | 默认值 | 说明 |
57
+ |-----------------|------|--------------------------|------|------------------------|
58
+ | `assetsDirPath` | 是 | `string` | - | 本地静态资源根目录，用于限制可上传的资源范围 |
59
+ | `pathAlias` | 否 | `Record<string, string>` | `{}` | 路径别名映射，用于解析代码中的资源引用 |
60
+ | `uploader` | 是 | `UploadAdapter` | - | 资源上传适配器，需返回资源的远程访问 URL |
61
+
62
+ ### 🔌 自定义上传适配器
63
+
64
+ 插件内部仅约定 上传接口规范，并不限制具体存储服务。
65
+ 你可以很方便地实现自己的上传适配器：
66
+
67
+ #### 接口定义
68
+
69
+ ```ts
70
+ import { LocalAssetInfo, defineUploaderAdapter } from '@taro-minify-pack/plugin-remote-assets'
71
+
72
+ interface LocalAssetInfo {
73
+ localPath: string; // 本地资源文件路径
74
+ uniqueKey: string; // 基于文件内容生成的 MD5 值
75
+ ext: string; // 文件扩展名
76
+ }
77
+
78
+ export interface CustomUploadAdapterOpt {
79
+ // 自定义适配器参数
80
+ }
81
+
82
+ export const customUploadAdapter = defineUploaderAdapter((opt: CustomUploadAdapterOpt) => {
83
+ return async (localAssetInfo: LocalAssetInfo): Promise<LocalAssetInfo & { remoteUrl: string }> => {
84
+ // 实现上传逻辑
85
+ // 返回包含远程 URL 的资源信息
86
+ return { ...localAssetInfo, remoteUrl: 'https://example.com/remote-asset.png' }
87
+ }
88
+ })
89
+ ```
90
+
91
+ #### 内置阿里云 OSS 适配器
92
+
93
+ 插件内置了阿里云 OSS 上传适配器，可直接使用：
94
+
95
+ ```ts
96
+ import { aliOssUploadAdapter } from '@taro-minify-pack/plugin-remote-assets'
97
+
98
+ interface AliOssUploadAdapterOpt {
99
+ customDomain?: string; // 自定义域名（可选）
100
+ bucketDir?: string; // OSS 存储目录（可选，默认根目录）
101
+ // 以下为阿里云 OSS 标准配置
102
+ accessKeyId: string;
103
+ accessKeySecret: string;
104
+ bucket: string;
105
+ region: string;
106
+ // ... 其他阿里云 OSS 配置
107
+ }
108
+ ```
109
+
110
+ ### 示例配置
111
+
23
112
  ```js
24
113
  // config/index.js
114
+ const path = require('path')
115
+ const { aliOssUploadAdapter } = require('@taro-minify-pack/plugin-remote-assets')
116
+
25
117
  module.exports = {
26
- plugins: [
27
- ['@taro-minify-pack/plugin-remote-assets', {
28
- // 路径别名
29
- pathAlias: {
30
- '@': path.resolve(__dirname, '../src/'),
31
- '~@': path.resolve(__dirname, '../src/'),
32
- },
33
- // 资源文件目录
34
- assetsDirPath: path.resolve(__dirname, '../src/assets/'),
35
- // 上传适配器
36
- uploader: aliOssUploadAdapter({
37
- customDomain:'https://your-custom-domain.com',
38
- accessKeyId: 'your-access-key-id',
39
- accessKeySecret: 'your-access-key-secret',
40
- bucket: 'your-bucket-name',
41
- bucketDir: 'bucketDir',
42
- region: 'your-region',
43
- })
44
- }],
45
- ],
46
- };
118
+ plugins: [
119
+ ['@taro-minify-pack/plugin-remote-assets', {
120
+ // 路径别名（用于解析代码中的资源引用）
121
+ pathAlias: {
122
+ '@': path.resolve(__dirname, '../src/'),
123
+ '~@': path.resolve(__dirname, '../src/'),
124
+ },
125
+ // 本地静态资源根目录
126
+ assetsDirPath: path.resolve(__dirname, '../src/assets/'),
127
+ // 上传适配器（以阿里云 OSS 为例）
128
+ uploader: aliOssUploadAdapter({
129
+ customDomain: 'https://your-custom-domain.com',
130
+ accessKeyId: 'your-access-key-id',
131
+ accessKeySecret: 'your-access-key-secret',
132
+ bucket: 'your-bucket-name',
133
+ bucketDir: 'taro-assets',
134
+ region: 'your-region',
135
+ }),
136
+ }],
137
+ ],
138
+ }
47
139
  ```
48
140
 
141
+ ## 🧠 工作原理简述
142
+
143
+ 1. **构建开始**：插件在构建开始时扫描指定的静态资源目录
144
+ 2. **资源分析**：
145
+ - 递归遍历目录下所有文件
146
+ - 基于文件内容生成 MD5 值作为唯一标识
147
+ - 检查缓存文件，跳过已上传的资源
148
+ 3. **并发上传**：使用 PromisePool 并发上传新资源（默认并发数：2）
149
+ 4. **生成缓存**：将上传结果写入缓存文件（node_modules/.cache/remote-assets-cache.json）
150
+ 5. **路径转换**：
151
+ - Babel 插件：替换 JS/TS 文件中的 import 语句
152
+ - PostCSS 插件：替换 CSS 文件中的 url() 引用
153
+ 6. **构建完成**：最终产物中静态资源路径已替换为远程 URL
154
+
155
+ ### 缓存机制
156
+
157
+ 插件使用本地缓存文件记录已上传的资源信息，避免重复上传：
158
+ - 缓存文件路径：`node_modules/.cache/remote-assets-cache.json`
159
+ - 缓存键：本地资源文件路径
160
+ - 缓存值：远程资源访问 URL
161
+ - 每次构建前会检查缓存，仅上传新的或修改过的资源
162
+
163
+ ### 资源唯一性校验
164
+
165
+ 为确保资源唯一性，插件使用文件内容的 MD5 值作为唯一标识：
166
+ - 即使文件名相同，只要内容不同，也会被视为不同资源
167
+ - 生成的 MD5 值会作为文件名的一部分上传到存储服务
168
+ - 确保同一资源不会被重复存储
169
+
170
+ ## 📌 适用场景
171
+
172
+ * 主包体积接近或超过微信限制（2MB）
173
+ * 图片、字体等静态资源较多
174
+ * 已使用远程 CDN / 对象存储服务
175
+ * 需要优化小程序加载速度
176
+
177
+ 如你正在配合 @taro-minify-pack 系列插件使用，可获得更完整的主包体积优化方案。
178
+
179
+ ## 🔍 代码示例
180
+
181
+ ### JS/TS 文件中的资源引用
182
+
183
+ ```tsx
184
+ // 原始代码
185
+ import logo from '@/assets/images/logo.png'
186
+
187
+ // 构建后自动转换为
188
+ const logo = 'https://your-cdn.com/taro-assets/2f9b7a8c9d0e1f2a3b4c5d6e7f8a9b0c.png'
189
+ ```
190
+
191
+ ### CSS 文件中的资源引用
192
+
193
+ ```css
194
+ /* 原始代码 */
195
+ .logo {
196
+ background-image: url('@/assets/images/logo.png');
197
+ }
198
+
199
+ /* 构建后自动转换为 */
200
+ .logo {
201
+ background-image: url('https://your-cdn.com/taro-assets/2f9b7a8c9d0e1f2a3b4c5d6e7f8a9b0c.png');
202
+ }
203
+ ```
204
+
205
+ ## 🤔 常见问题
206
+
207
+ ### 1. 为什么有些资源没有被上传？
208
+
209
+ - 请检查资源是否在指定的 `assetsDirPath` 目录下
210
+ - 检查资源引用路径是否正确
211
+ - 确保路径别名配置正确
212
+
213
+ ### 2. 为什么修改了资源后没有重新上传？
214
+
215
+ - 插件基于文件内容的 MD5 值判断资源是否修改
216
+ - 如果仅修改了文件名而内容未变，不会重新上传
217
+ - 如需强制重新上传，可删除缓存文件后重新构建
218
+
219
+ ### 3. 如何处理动态引入的资源？
220
+
221
+ - 插件目前仅支持静态 import 和 url() 引用
222
+ - 动态引入的资源（如使用变量拼接路径）需要手动处理
223
+
224
+ ### 4. 上传失败怎么办？
225
+
226
+ - 检查上传适配器配置是否正确
227
+ - 确保网络连接正常
228
+ - 查看构建日志获取详细错误信息
229
+
230
+ ### 5. 如何自定义缓存文件路径？
231
+
232
+ - 当前版本不支持自定义缓存文件路径
233
+ - 缓存文件固定在 `node_modules/.cache/remote-assets-cache.json`
234
+
235
+ ## 📄 许可证
236
+
237
+ MIT License
238
+
239
+ ## 🤝 贡献
240
+
241
+ 欢迎提交 Issues 和 Pull Requests！
242
+
243
+ > 该插件是 @taro-minify-pack 系列插件的一部分，致力于提供完整的 Taro 项目优化解决方案。
package/dist/index.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { RemoteAssetPluginOpt } from './types';
2
2
  import { IPluginContext } from '@tarojs/service';
3
- export { RemoteAssetPluginOpt } from './types';
3
+ export * from './types';
4
4
  export * from './upload-adapter';
5
5
  declare const _default: (ctx: IPluginContext, pluginOpts: RemoteAssetPluginOpt) => void;
6
6
  export default _default;
package/dist/index.js CHANGED
@@ -30,6 +30,7 @@ const path_1 = __importDefault(require("path"));
30
30
  const upload_assets_1 = require("./upload-assets");
31
31
  const utils_1 = require("./utils");
32
32
  const path_transform_1 = require("./path-transform/path-transform");
33
+ __exportStar(require("./types"), exports);
33
34
  __exportStar(require("./upload-adapter"), exports);
34
35
  const cacheFilePath = path_1.default.resolve(process.cwd(), 'node_modules', '.cache/remote-assets-cache.json');
35
36
  exports.default = (ctx, pluginOpts) => {
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gDAAuB;AAGvB,mDAA8C;AAC9C,mCAAqD;AACrD,oEAA+D;AAI/D,mDAAgC;AAEhC,MAAM,aAAa,GAAG,cAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,iCAAiC,CAAC,CAAA;AAEpG,kBAAe,CAAC,GAAmB,EAAE,UAAgC,EAAE,EAAE;IACvE,MAAM,SAAS,GAAG,IAAA,8BAAa,EAAC,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC,CAAA;IAEzF,GAAG,CAAC,YAAY,CAAC,GAAS,EAAE;QAC1B,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,GAAG,UAAU,CAAA;QAC9C,MAAM,SAAS,GAAG,IAAA,oBAAY,EAAC,aAAa,CAAC,CAAA;QAC7C,MAAM,mBAAmB,GAAG,MAAM,IAAA,4BAAY,EAAC,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAA;QAC9F,MAAM,kBAAkB,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE;YACrE,uCAAY,MAAM,KAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,SAAS,IAAE;QACxD,CAAC,EAAE,SAAS,CAAC,CAAA;QACb,IAAA,qBAAa,EAAC,aAAa,EAAE,kBAAkB,CAAC,CAAA;IAClD,CAAC,CAAA,CAAC,CAAA;IAEF,GAAG,CAAC,gBAAgB,CAAC,CAAC,aAAa,EAAE,EAAE;QACrC,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,aAAa,CAAC,IAAI,CAAA;QACtD,MAAM,8BAA8B,GAAG,cAAI,CAAC,OAAO,CAAC,SAAS,EAAE,yCAAyC,CAAC,CAAA;QACzG,aAAa,CAAC,IAAI,CAAC,OAAO,mCACrB,cAAc,KACjB,CAAC,8BAA8B,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,EAAE,GAC3E,CAAA;IACH,CAAC,CAAC,CAAA;IAEF,GAAG,CAAC,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;QACnC,MAAM,4BAA4B,GAAG,cAAI,CAAC,OAAO,CAAC,SAAS,EAAE,uCAAuC,CAAC,CAAA;QAErG,KAAK,CAAC,MAAM;aACT,IAAI,CAAC,QAAQ,CAAC;aACd,GAAG,CAAC,aAAa,CAAC;aAClB,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,4BAA4B,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,CAAA;IAC1E,CAAC,CAAC,CAAA;AACJ,CAAC,CAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gDAAuB;AAGvB,mDAA8C;AAC9C,mCAAqD;AACrD,oEAA+D;AAE/D,0CAAuB;AAEvB,mDAAgC;AAEhC,MAAM,aAAa,GAAG,cAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,iCAAiC,CAAC,CAAA;AAEpG,kBAAe,CAAC,GAAmB,EAAE,UAAgC,EAAE,EAAE;IACvE,MAAM,SAAS,GAAG,IAAA,8BAAa,EAAC,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC,CAAA;IAEzF,GAAG,CAAC,YAAY,CAAC,GAAS,EAAE;QAC1B,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,GAAG,UAAU,CAAA;QAC9C,MAAM,SAAS,GAAG,IAAA,oBAAY,EAAC,aAAa,CAAC,CAAA;QAC7C,MAAM,mBAAmB,GAAG,MAAM,IAAA,4BAAY,EAAC,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAA;QAC9F,MAAM,kBAAkB,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE;YACrE,uCAAY,MAAM,KAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,SAAS,IAAE;QACxD,CAAC,EAAE,SAAS,CAAC,CAAA;QACb,IAAA,qBAAa,EAAC,aAAa,EAAE,kBAAkB,CAAC,CAAA;IAClD,CAAC,CAAA,CAAC,CAAA;IAEF,GAAG,CAAC,gBAAgB,CAAC,CAAC,aAAa,EAAE,EAAE;QACrC,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,aAAa,CAAC,IAAI,CAAA;QACtD,MAAM,8BAA8B,GAAG,cAAI,CAAC,OAAO,CAAC,SAAS,EAAE,yCAAyC,CAAC,CAAA;QACzG,aAAa,CAAC,IAAI,CAAC,OAAO,mCACrB,cAAc,KACjB,CAAC,8BAA8B,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,EAAE,GAC3E,CAAA;IACH,CAAC,CAAC,CAAA;IAEF,GAAG,CAAC,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;QACnC,MAAM,4BAA4B,GAAG,cAAI,CAAC,OAAO,CAAC,SAAS,EAAE,uCAAuC,CAAC,CAAA;QAErG,KAAK,CAAC,MAAM;aACT,IAAI,CAAC,QAAQ,CAAC;aACd,GAAG,CAAC,aAAa,CAAC;aAClB,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,4BAA4B,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,CAAA;IAC1E,CAAC,CAAC,CAAA;AACJ,CAAC,CAAA"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@taro-minify-pack/plugin-remote-assets",
3
- "version": "0.0.5-alpha.4",
3
+ "version": "0.0.5-alpha.6",
4
4
  "description": "",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
package/src/index.ts CHANGED
@@ -5,7 +5,7 @@ import { uploadAssets } from './upload-assets'
5
5
  import { getCacheData, saveCacheData } from './utils'
6
6
  import { pathTransform } from '@/path-transform/path-transform'
7
7
 
8
- export { RemoteAssetPluginOpt } from '@/types'
8
+ export * from '@/types'
9
9
 
10
10
  export * from './upload-adapter'
11
11