在使用 Webpack 构建 Vue 3 项目时，开发者接触最多的是 vue-loader 这类官方工具，它负责把 .vue 单文件组件拆分成 template、script、style 三个部分交给不同的 loader 处理。但当你遇到一些定制化需求时，比如团队内部的私有模板语法、需要对源码做统一的代码注入、或者要在构建阶段对资源做特殊转换，官方 loader 就不够用了，这时候自定义 loader 就成了必须掌握的技能。
Loader 的执行原理与完整链路
要写出可靠的 loader，首先要理解 Webpack 中一个模块从源文件到可执行代码的完整过程。当 Webpack 解析到一个模块依赖时，它会根据模块的文件后缀和 module.rules 中的匹配规则，找出该文件需要经过的所有 loader，组成一条处理链。默认情况下，这条链是从右到左、从下到上执行的，也就是说配置中写在最后的 loader 最先执行。
举个例子，一条常见的样式规则如下：
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: [
'style-loader', // 最后执行：把样式注入 DOM
'css-loader', // 其次：处理 import 和 url()
'postcss-loader' // 最先执行：处理浏览器兼容前缀
]
}
]
}
};每个 loader 接收上游传来的字符串内容，处理后再把结果传给下游，最终交给 Webpack 做模块化包装。理解这个数据流非常关键：loader 本质上就是一个「输入字符串、输出字符串」的纯转换函数，只是它挂载了一个携带构建上下文的 this 对象。
手写一个处理 Vue 单文件组件的自定义 loader
假设团队内部约定了一种简化版的组件写法，在 .vue 文件中使用了自定义的 <docs> 标签来承载组件文档，我们希望在构建时把这段文档内容提取出来，注入到组件的 defineOptions 中，方便开发环境下做组件预览。下面就来实现这个 loader。
先创建 loaders/docs-inject-loader.js 文件，核心代码如下：
const parser = require('@vue/compiler-sfc');
module.exports = function docsInjectLoader(source) {
// 异步 loader 写法，先拿到回调
const callback = this.async();
// 解析单文件组件，分离出各个块
const { descriptor } = parser.parse(source, {
filename: this.resourcePath
});
// 提取 docs 块中的内容
const docsBlock = descriptor.customBlocks.find(
block => block.type === 'docs'
);
const docsText = docsBlock ? docsBlock.content.trim() : '';
// 删除自定义块后重新拼接 SFC 内容
let newSource = source;
if (docsBlock) {
newSource = source.slice(0, docsBlock.loc.start.offset)
+ source.slice(docsBlock.loc.end.offset);
}
// 把文档文本注入到组件选项中
const injectScript = `
<script>
import { defineOptions } from 'vue';
defineOptions({ __docs__: ${JSON.stringify(docsText)} });
</script>
`;
callback(null, newSource + injectScript);
};这段代码中有几个值得注意的点。第一，使用 this.async() 可以把同步 loader 转成异步模式，当你需要在 loader 里做文件读写或网络请求时必须使用这种方式。第二，this.resourcePath 拿到的是当前处理文件的绝对路径，可以用来做缓存 key 或日志定位。第三，注入的脚本要放在 SFC 内容之后，这样 vue-loader 后续拆分时才能把 defineOptions 合并进组件。
接着在 vue.config.js 或者原生的 webpack.config.js 中注册它：
module.exports = {
module: {
rules: [
{
test: /\.vue$/,
enforce: 'pre', // 在 vue-loader 之前执行
use: [
{
loader: path.resolve(__dirname, 'loaders/docs-inject-loader.js')
}
]
}
]
}
};enforce: 'pre' 保证了自定义 loader 在 vue-loader 之前运行，这样我们处理的还是原始 SFC 文本。相对应的还有 enforce: 'post'，它会让 loader 排到最后执行，常用于做代码检查或产物分析。
Loader 与 Plugin 的职责边界及进阶技巧
很多人分不清什么时候该写 loader、什么时候该写 plugin，判断标准其实很简单：loader 是文件级别的转换器，plugin 是流程级别的拦截器。如果你要改变某个文件的内容，用 loader；如果你要在构建的某个生命周期节点做事情，比如打包完成后上传资源、动态修改编译产物、监听编译错误，那就得用 plugin，通过 compiler.hooks 挂载钩子来实现。
在真实项目中，loader 的性能直接影响构建速度，有几个实践建议值得遵循。首先，尽量利用 this.cacheable() 标记 loader 可缓存，这样文件没变化时 Webpack 会直接复用上次结果。其次，处理大文件时避免同步阻塞，一律用 this.async() 拿到回调再返回。最后，谨慎使用 this.addDependency()，它用于声明额外依赖文件，声明过多会让缓存频繁失效。
调试 loader 也有便捷手段，可以借助 loader-utils 中的 getOptions 读取配置，或者直接在 loader 中插入 console.log 配合 node --inspect-brk 断点调试。对于复杂场景，还可以了解一下 pitch 阶段：loader 链在真正执行前会先从左到右走一遍 pitch 函数，如果某个 loader 的 pitch 直接返回了内容，后面所有的 loader 都会被跳过，style-loader 正是利用这个机制拦截了本不该执行的 loader，实现按需加载样式。
掌握自定义 loader 之后，你会发现很多原本需要改动业务代码的需求，都可以下沉到构建层统一处理，这正是前端工程化的价值所在。无论是代码规范检查、私有语法转换还是自动化注入，loader 都提供了干净且可控的切入点，配合 Vue 3 的编译时能力，可以打造出高度定制化的研发体系。
Webpack loaderVue 3 工程化自定义插件修改时间：2026-09-09 23:48:38