@rollup/plugin-url 使用及原理介绍
一款用于将导入的文件转换成 data-uri 或者 es 模块的插件。
安装
npm install @rollup/plugin-url -D
使用
在 rollup.config.js 文件中引入插件并进行简单配置。
import url from '@rollup/plugin-url';
export default {
input: 'src/index.js',
output: {
dir: 'output',
format: 'cjs'
},
plugins: [url()]
};
比如，可以直接获取 svg 的 data-uri，或者是 esm 模块，浏览器可以自行解析。
import svg from './image.svg';
console.log(`svg contents: ${svg}`);
默认小于 14kb 的文件会以 base64 的格式内联到项目中，大于 14kb 的会移动到打包文件所在的目录（以静态资源的方式存在）。
配置
include
Type: String | String[]
Default: []
一个 picomatch 规则，用于说明哪些文件需要处理。默认都会处理 .svg, .png, .jpg, .jpeg, .gif and .webp后缀的文件。
exclude
Type: String | String[]
Default: node_modules/**
一个 picomatch 规则，用于说明那些文件不需要处理。
limit
Type: Number
Default: 14336 (14kb)
设置可以内联的最大文件大小。如果文件超过这个限制，就会复制到目标目录，同时提供一个 hash 文件名，设置为 0 的话将会复制全部匹配文件。
publicPath
Type: String
Default: ‘’
在复制文件时往文件名前面添加前缀字符。
emitFiles
Type: Boolean
Default: true
如果设置成 false，那么会组织插件生成文件。这对于客户端打包和服务端打包非常有用。
fileName
Type: String
Default: '[hash][extname]'
如果 emitFiles 设置成 true，那么这个配置可以对生成的文件进行重命名。可以接受以下占位符：
- [hash]：文件的 hash 值。
- [name]：导入的文件名，不包含文件后缀。
- [extname]：导入文件的后缀，包含 . 。
- [dirname]：导入文件的父目录名，包含 / 后缀。
sourceDir
Type: String
Default: ‘’
当在 fileName 字段中使用到了 [dirname] 占位符时，可以通过 sourceDir 字段来改变生成的父目录名，比如：
在 src/path/to/file.js 中引入 image.png
import png from './image.png';
在配置中移除 src 目录：
url({
fileName: '[dirname][hash][extname]',
sourceDir: path.join(__dirname, 'src')
});
那么最终生成的文件目录结构为 path/to/image.png。
destDir
Type: String
Default: ‘’
复制文件到指定目录。
原理
在 load 构建钩子中对导入的模块 id 进行判断，满足条件（通过 include 字段继续配置）的文件就会进行处理：
// 默认支持处理的文件
const defaultInclude = ['**/*.svg', '**/*.png', '**/*.jp(e)?g', '**/*.gif', '**/*.webp'];
{
load(id) {
// 继续过滤
if (!filter(id)) {
return null;
}
}
}
使用 fs 模块获取文件的大小分析是否需要转换成 base64 内联到项目代码中。
// 复制文件逻辑
if ((limit && stats.size > limit) || limit === 0) {
...
} else {
// 生成 base64 内联到项目代码中的逻辑
}
生成 base64
通过 mime 库对导入的文件的 MIME-TYPE 进行分析，data-uri 需要标注文件类型 data:xxxx;
const mimetype = mime.getType(id);
const isSVG = mimetype === 'image/svg+xml';
// 转成 base64，svg 不做处理
data = isSVG ? encodeSVG(buffer) : buffer.toString('base64');
const encoding = isSVG ? '' : ';base64';
data = `data:${mimetype}${encoding},${data}`;
return `export default "${data}"`;
svg 本身就是一种比较安全的格式，也可以直接用 data-uri 的方法进行使用，同时转化成 base64 也会导致体积增大，因此通常情况下都是不进行转化的。
复制文件
在这个逻辑当中，需要处理文件目录、文件名及修改导入文件的路径。
修改导入路径
// 根据文件内容生成 hash
const hash = crypto.createHash('sha1').update(buffer).digest('hex').substr(0, 16);
// 文件后缀
const ext = path.extname(id);
// 文件名
const name = path.basename(id, ext);
const relativeDir = options.sourceDir
? // 根据配置的 sourceDir 对生成的文件的目录层级进行改变
path.relative(options.sourceDir, path.dirname(id))
: // 默认只需要找到上一级父目录即可
path.dirname(id).split(sep).pop();
// 替换占位符
const outputFileName = fileName
.replace(/\[hash\]/g, hash)
.replace(/\[extname\]/g, ext)
// use `sep` for windows environments
.replace(/\[dirname\]/g, relativeDir === '' ? '' : `${relativeDir}${sep}`)
.replace(/\[name\]/g, name);
// 生成的文件路径作为这个资源文件的导入
data = `${publicPath}${outputFileName.split(sep).join(posix.sep)}`;
// 记录有多少个文件需要复制
copies[id] = outputFileName;
return `export default "${data}"`;
因此我们的 import 导入的资源到最后会被解析成一个路径：
import logo from './path/to/image/logo.png';
// 被打包成：
var logo = 'path/to/image/-fd8e5181bb448b02.png';
生成目录
在 load 钩子中对导入的文件进行解析，解析文件复制之后的相对路径。在 generateBundle 钩子中就是复制这个文件到打包结果中。
可以通过配置 destDir 来复制文件到指定目录。
const base = options.destDir || outputOptions.dir || path.dirname(outputOptions.file);
使用 make-dir 库创建文件夹，使用 fs 模块复制文件。
await makeDir(base);
await Promise.all(
// 对记录好的文件进行复制
Object.keys(copies).map(async (name) => {
const output = copies[name];
const outputDirectory = path.join(base, path.dirname(output));
await makeDir(outputDirectory);
return copy(name, path.join(base, output));
})
);
svg 编码
function encodeSVG(buffer) {
return (
encodeURIComponent(
buffer
.toString('utf-8')
// strip newlines and tabs
.replace(/[\n\r]/gim, '')
.replace(/\t/gim, ' ')
// strip comments
.replace(/<!--(.*(?=-->))-->/gim, '')
// replace
.replace(/'/gim, '\\i')
)
// encode brackets
.replace(/\(/g, '%28')
.replace(/\)/g, '%29')
);
}