夜雨聆风@rollup/plugin-inject是rollup官方自带的一个插件，是对标webpack中ProvidePlugin的存在。inject插件功能实用，源码也很值得阅读。今天我就为大家详解inject插件的使用。
一句话概括插件是干嘛的？
@rollup/plugin-inject 会通过语法解析与作用域分析，扫描代码中未声明的全局变量使用，自动在对应模块顶部插入精准的 import 语句，将全局变量的引用替换为从指定模块的具名 / 默认导入，彻底替代 “全局污染式” 的变量引用。
核心本质：把 “全局变量” 变成 “显式导入”，保留使用便捷性的同时，遵循 ES Module 规范，消除全局依赖隐患。
应用场景
环境变量注入
inject({
modules: {
PUBLIC_KEY: ["@/config", "PUBLIC_KEY"]
}
});
示例代码
console.log(PUBLIC_KEY);
转换后
import { PUBLIC_KEY } from"@/config";
console.log(PUBLIC_KEY);
相比replace插件，inject插件包括了语法解析和作用域分析，可以确保是全局变量才给替换。而且避免了超大数据重复而增大体积。
Polyfill注入
我们常用的polyfill是污染性的，本质就是挂在全局变量上。使用inject插件，可以在不污染全局变量的情况下使用polyfill。
比如许多库中常有判断某些特性是否支持，理想情况是遇到什么差异，就应该用什么特性来判断。然而业界常常一言不合就用 XMLHttpRequest 来判断是否是IE6，也不管是不是用于请求的场景。如果我们在全局加入 XMLHttpRequest 就会导致许多地方误判。
我们使用inject插件纯净注入polyfill并指定范围，只在有限的地方注入，避免其他地方误判。
配置
inject({
modules: {
XMLHttpRequest: ["any-xhr-polyfill", 'default']
},
// 控制注入范围，只在ajax封装工具内有效
include: ["some-ajax-util"]
});
转换前
// xxx-ajax.js
var xhr = newXMLHttpRequest();
// 其他位置
var isIE6 = typeofXMLHttpRequest === "undefined"
转换后
// xxx-ajax.js
// 由于这个文件在插件的include范围内。会被改成import引入。
importXMLHttpRequestfrom'any-xhr-polyfill';
var xhr = newXMLHttpRequest();
// 其他位置
// 由于这个文件不在插件的include范围内。保持原样。
var isIE6 = typeofXMLHttpRequest === "undefined"
理论上，所有不可完全实现功能的polyfill（sham）都需要纯净注入。因为使用时如果无法完整实现时需要判断和降级。
全局变量模拟
在传统js引入时往往采用全局变量来使用。在工程化项目中往往使用npm包来管理。这时候可以使用inject插件来转化。
// 配置
inject({
modules: {
$: "jquery"
}
});
// 原始代码
$("#app").addClass("active");
// 转换后
import $ from"jquery";
$("#app").addClass("active");
特定运行环境SDK模拟
例如，我在编写云闪付小程序时发现一个问题。使用云闪付开发者工具无法模拟云闪付upsdk的行为。于是，可以使用inject插件来模拟：
inject({
modules: {
upsdk: ["@/utils/upsdk", "*"]
}
});
这样，在开发环境中，代码中的 upsdk 会自动指向我们模拟的实现，而在生产环境中则可以指向真实的SDK。
全局变量隔离
在一些复杂的项目中，可能存在多个模块或库同时使用相同的全局变量名，但实际指向不同的实现。如果这些变量直接挂在全局，可能会导致冲突或不可预期的行为。@rollup/plugin-inject 可以帮助我们隔离全局变量，为每个模块提供独立的变量实例，而不是共享同一个全局对象。
module.exports = {
plugins: [
inject({
modules: {
api: ["@/utils/impl1", '*']
},
include: ["src/xxxx"]
}),
inject({
modules: {
api: ["@/utils/impl2", '*']
},
include: ["src/yyyy"]
})
]
};
上述示例配置表达了：一个全局变量“api”，在不同文件夹的源代码中有不同的实现。
插件顺序与最佳实践
@rollup/plugin-inject 应该放在 plugins 数组靠后的位置。因为inject插件是一个兜底插件，如果业务插件中产生了全局变量，要在后面用inject插件才是正确的。
但是inject插件要在处理import的插件前运行，比如和rollup-plugin-import在一起时就要在rollup-plugin-import的前面。
大致转换顺序如下：
非es格式转es(如json、typescript) 业务转换规则(如vite的import.meta.glob、new URL('xxx', import.meta.url)转化) @rollup/plugin-inject插件(这是兜底性的插件) rollup-plugin-import插件(这也是兜底性的插件，要处理inject插件生成的import)
插件在边界场景的处理
inject插件有语法解析和作用域分析，因此内部变量能够正常处理。业界的一些构建策略一味地追求构建速度，直接字符串替换了，也是令人难绷。
// 看看以下示例配置在极端情况的表现
inject({
modules: {
foo: ["@/config", "foo"]
}
});
作用域分析
inject插件能正确识别到内部变量
// 这个foo是全局变量，会被注入
console.log(foo);
exportfunctionbar() {
var foo = 1;
// 这个foo是内部变量，保持原样
console.log(foo);
};
转化后
import { foo } from"@/config";
// 这个foo是全局变量，被转化为import引入了
console.log(foo);
exportfunctionbar() {
var foo = 1;
// 这个foo是内部变量，保持原样
console.log(foo);
};
对象表达式的属性缩写
inject插件能正确识别到对象表达式的属性缩写
console.log({ foo });
转化后
import { foo } from"@/config";
console.log({ foo });
静态块
inject插件在 static 块下作用域分析不正确
// 此处foo是全局变量，但是会被inject插件误判为static内的var，导致没有被替换
console.log(foo);
exportclassBar {
static {
var foo = 1;
}
}
这个不是rollup特有的问题，是业界普遍存在的问题。好在rollup是个活跃项目，笔者在发稿前已经提了PR，相信不久以后就能更新。
插件的局限性
inject能够按模块注入全局变量，但是在polyfill处理场景，更希望根据情况选择性注入。
constKEY = typeofSymbol === "function" ?
Symbol() :
'__key'
上面示例代码中更希望typeof Symbol不注入，判断的是原生变量；调用Symbol()要注入，用来支持不兼容的浏览器。
再有，setTimeout 2个参数不注入，多个参数要注入等。
这些针对polyfill处理的场景，应该使用更专业的rollup-plugin-polyfill-inject。
总结
@rollup/plugin-inject 是一个精巧且实用的官方插件，它通过对 AST 的语法解析和作用域分析，优雅地解决了全局变量转换为模块导入的问题。无论是环境变量注入、还是开发环境的 SDK 模拟，它都能胜任。虽然它在 static 块等极少数边界场景下还有待完善，且缺乏更细粒度的条件注入能力，但在绝大多数场景下，它都是替代粗暴的字符串替换方案的最佳选择。掌握 inject 插件，能让你的 rollup 工程化方案更加健壮与优雅。
