build-plugin-js-assets-local

基于 build-scripts 扩展插件，用于在 build 时将 js 中 cdn 图片下载到本地并替换为 PublicPath 的路径。

例如 js 中应用/使用了 cdn 图片：https://img.alicdn.com/imgextra/i2/tps-360-96.png 会被替换为：${PublicPath}/assets/imgextra/i2/tps-360-96.png

v2 起内部由 processAssets 阶段插件改造为 webpack enforce: 'post' loader：

• .json 模块由 webpack 内置 JsonParser 处理，不会经过本 loader，从根源避免误改 JSON 内嵌的 CDN URL；
• webpack 自身运行时代码同样不参与用户 loader 链，不再被误命中；
• 注入的 __webpack_require__.p 拼接形式与 v1 完全一致，对消费端零改动。

Install

npm i build-plugin-js-assets-local@^0.1.0 -D

Usage

• build.config.js 配置文件

module.exports = {
  plugins: [
    [
      "build-plugin-js-assets-local",
      {
        enabled: true, // 控制开启，可不配
        assetsPath: "assets", // 下载资源目录，可不配
        removeManifest: false, // 是否删除manifest文件，可不配
        manifestFilePath: "manifest.json", // manifest文件路径，可不配
        activeInDev: false, // 是否在开发阶段生效，默认关闭
        matchReg: `(https?:)?\/\/(img|o|g|gw|dev\.g|dev\.o|at)\.alicdn\.com\/(imgextra|t)\/.*?\.(png|gif|jpg|jpeg|svg|js)`, // 正则匹配cdn图片和cdn js，默认可不配
        // 以下为 v2 新增可选项，老接入点不配即按默认行为
        // publicPath: "auto",                 // 不传则自动取 webpack output.publicPath
        // outputPath: "",                     // 不传则自动取 webpack output.path
        // test: /\.(js|jsx|ts|tsx|mjs|cjs)$/, // loader 命中后缀，默认仅匹配项目 JS 源码
        // include: [/src/],                   // 额外纳入处理的目录/正则，可传单值或数组
        // exclude: [/some-pure-pkg/],         // 如确认某些包不含需本地化的 CDN 可显式排除
        // fastFilter: "alicdn.com",           // 字节级预检；支持逗号分隔多关键词，自定义 matchReg 时请同步修改；设为 null 关闭预检
      },
    ],
  ],
};

• package.json scripts 配置

{
  "scripts": {
    "build": "icejs build --config build.config.js"
  }
}

入参说明

| 参数 | 类型 | 默认值 | 说明 | | ------------------ | --------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | enabled | boolean | true | 总开关，关闭后插件完全不注册（manifest 也不会产出） | | activeInDev | boolean | false | dev (start) 阶段是否启用 CDN 本地化；关闭时仅产出 manifest | | assetsPath | string | "assets" | 下载到产物目录下的子路径 | | manifestFilePath | string | "manifest.json" | manifest 输出文件名 | | removeManifest | boolean | false | 构建完成后是否删除 manifest | | matchReg | string \| RegExp | 阿里 CDN 默认正则 | CDN URL 命中规则 | | publicPath | string | ""（取 webpack output.publicPath） | 本地化后路径前缀；"auto" 时注入 __webpack_require__.p | | outputPath | string | ""（取 webpack output.path） | 资源下载根目录 | | test | RegExp | /\.(js\|jsx\|ts\|tsx\|mjs\|cjs)$/ | v2 新增，loader 命中文件类型 | | include | string \| RegExp \| Array | — | v2 新增，额外纳入命中范围 | | exclude | string \| RegExp \| Array | — | v2 新增，默认不排除 node_modules（以免遗漏 @alibsp 等包内需本地化的 CDN）；性能依赖 fastFilter 兜底 | | fastFilter | string \| null | "alicdn.com" | v2 新增，字节级预检。支持逗号分隔多关键词（任一命中即通过）；自定义 matchReg 时请同步修改；设为 null 或空串则关闭预检 |

升级说明（v1 → v2）

所有 v1 入参的语义、默认值均保持不变，老接入点零改动即可使用。v2 仅做了内部实现迁移：

• 工作时机：compilation.processAssets ⇒ webpack post loader（在 babel/ts 转译之后、chunk 拼接之前）；
• 处理粒度：从「最终 chunk 文本」⇒「单个 module 文本」；
• 跨来源误改修复：.json 模块、webpack runtime 代码不再被扫描；
• sourcemap：loader 不主动维护字面量级映射，由后续 webpack/Terser 阶段自然重建（与 v1 整体行为一致）。

性能说明

post loader 会被包含 node_modules 在内的所有匹配 module 触发。考虑到部分第三方包（例如 @alibsp/* 内部包）也含需本地化的阿里 CDN 资源，插件默认不排除 node_modules，以免功能遗漏。性能依靠以下两道闸门兑换：

1. fastFilter: "alicdn.com"　进入 loader 后先 String#includes 预检，不含关键词的模块直接跳过。支持英文逗号分隔多个关键词（如 "alicdn.com,your-cdn.com"），任一命中即通过。该字节级检测平均不到 0.05ms/模块，对 1k–5k 范围的 module 额外耗费 < 250ms。
2. webpack 5 module cache　二次构建 / HMR 不会重跑 loader，增量成本趋近于 0。

如果你完全确认某些包不含需本地化的 CDN、希望进一步压缩首构耗时，可显式传 exclude 跳过调度。如果重定义了 matchReg，请同步修改 fastFilter（如 "your-cdn.com" 或 "alicdn.com,your-cdn.com"）；设为 null 可关闭预检。