为Webpack5项目引入Buffer Polyfill

前言

最近在公司的一个项目中使用到了Webpack5, 然而在使用某个npm包的时候,出现了Buffer is not defined 这个问题,原因很明显了,因为浏览器运行时没有Buffer这个API,所以需要为浏览器引入Buffer Polyfill.

截屏2022-12-06 16.40.27.png

Webpack5

这种在Webpack项目下使用NodeJS包的场景应该是很常见的,为什么之前没有遇到过这个问题。因为Webpack5之前的版本,Webpack会自动为我们引入NodeJS API Polyfill, 然而Webpack5之后,官方认为自动引入Polyfill会导致bundle体积过大,并且大多数情况下这些自动引入的Polyfill是没有用到的。所以Webpack5需要我们手动引入Polyfill

配置Webpack5

安装Buffer Polyfill

我们需要先安装兼容浏览器环境的Buffer实现。这里使用的是buffer这个npm包

1
npm install -D buffer

配置 Fallback

Webpack resolve.fallback指定了当我们的目标构建环境中不存在对应的包时,将使用fallback的值作为回退。这里我们使用安装的buffer包作为fallback

1
2
3
4
5
6
7
{
resolve: {
fallback: {
buffer: require.resolve('buffer/'),
},
},
}

这里使用了’buffer/‘, 这样可以明确告诉NodeJS模块查询算法,使用buffer npm包,而不是NodeJS自带的buffer模块

配置ProvidePlugin

Webpack ProvidePlugin可以注入一个模块或者值,作为全局变量。我们之后可以直接使用被注入的全局变量,无需import/require

1
2
3
4
5
6
7
{
plugins: [
new webpack.ProvidePlugin({
Buffer: ['buffer', 'Buffer'], // ['包名', '包中的值']
})
]
}

上面的配置相当于

1
const Buffer = require('buffer').Buffer;

完整配置

1
2
3
4
5
6
7
8
9
10
11
12
{
resolve: {
fallback: {
buffer: require.resolve('buffer/'),
},
},
plugins: [
new webpack.ProvidePlugin({
Buffer: ['buffer', 'Buffer'],
})
]
}

package.json browser字段

经过上面的配置,正常情况下就可以解决Buffer is not defined 这个问题了。然而我使用的公司内部的某个npm包却报出了新的问题Cannot read properties of undefined(reading 'allocUnsafe') , 其它依赖buffer的包则一切正常。

截屏2022-12-06 16.38.54.png

经过排查,和这个包的package.json browser字段有关。

1
2
3
4
5
6
// package.json
{
"browser": {
"buffer": false
}
}

按照非npm官方规范(https://github.com/defunctzombie/package-browser-field-spec),browser可以有三种用途

  1. main字段的替代。npm官方文档中介绍的用途,值为string类型,用于指定浏览器环境的包入口

    1
    "browser": "./browser/specific/main.js"
  2. 替代指定文件。左侧为你需要替换的模块或文件名称,右侧为替换项

    1
    2
    3
    4
    "browser": {
    "module-a": "./shims/module-a.js",
    "./server/only.js": "./shims/client-only.js"
    }
  3. 忽略模块。设置false可以阻止模块或文件被打包到包中

    1
    2
    3
    "browser": {
    "module-a": false
    }

    以上配置会导致a为undefined

    1
    const a = require('module-a');

解决方法也很简单,让包的维护者把package.json中的browser字段删除即可。至此,所有报错全部解决,可以愉快地使用Buffer API了

结语

Webpack5不再自动为我们引入NodeJS Polyfill, 我们可以安装兼容浏览器环境的npm包,然后通过配置resolve.fallback以及providePlugin插件来手动引入;如果配置完成后,某些包还是有问题,可以尝试检查对应包中的package.json browser字段