在Laravel项目中为VueJS 3设置compilerOptions.isCustomElement
技术背景
在Laravel项目中使用VueJS 3时，若引入了提供自定义元素的JS文件，可能会遇到组件解析失败的控制台错误，提示需要通过compilerOptions.isCustomElement将某些元素排除在组件解析之外。
实现步骤
Webpack项目（webpack.mix.js）
在webpack.mix.js文件中添加如下配置：
1
2
3
4
5
6
7
| mix.js('resources/assets/js/app.js', 'public/js').vue({
options: {
compilerOptions: {
isCustomElement: (tag) => ['md-linedivider'].includes(tag),
},
},
});
|
Vite项目（vite.config.js/ts）
在vite.config.js或vite.config.ts中配置：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [
vue({
template: {
compilerOptions: {
isCustomElement: (tag) => ['md-linedivider'].includes(tag),
}
}
})
]
})
|
Nuxt 3项目（nuxt.config.ts）
在nuxt.config.ts中设置：
1
2
3
4
5
6
7
| export default defineNuxtConfig({
vue: {
compilerOptions: {
isCustomElement: (tag) => ['lite-youtube'].includes(tag),
},
}
})
|
使用vue-loader的Webpack项目
在Webpack配置文件中：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| module.exports = {
module: {
rules: [
{
test: /\.vue$/,
loader: "vue-loader",
options: {
enableTsInTemplate: true,
compilerOptions: {
isCustomElement: (tag) => ["hidden", "font"].includes(tag)
}
},
},
]
}
}
|
核心代码
以下是不同构建工具下的核心配置代码示例：
Webpack
1
2
3
4
5
6
7
| mix.js('resources/assets/js/app.js', 'public/js').vue({
options: {
compilerOptions: {
isCustomElement: (tag) => ['your-custom-tag'].includes(tag),
},
},
});
|
Vite
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
export default defineConfig({
plugins: [
vue({
template: {
compilerOptions: {
isCustomElement: (tag) => tag.startsWith('your-prefix-'),
},
},
}),
],
});
|
Nuxt 3
1
2
3
4
5
6
7
8
9
| import { defineNuxtConfig } from 'nuxt';
export default defineNuxtConfig({
vue: {
compilerOptions: {
isCustomElement: (tag) => ['your-custom-element'].includes(tag),
},
},
});
|
最佳实践
- 明确自定义元素：准确识别需要排除的自定义元素，避免将正常的Vue组件误判为自定义元素。
- 代码复用：将自定义元素的判断逻辑封装成函数，方便在不同的配置文件中复用。
- 版本兼容性：确保所使用的构建工具和Vue版本兼容，避免因版本不匹配导致配置失效。
常见问题
代码生成节点缺失错误
在配置compilerOptions.isCustomElement后，可能会出现“Codegen node is missing for element/if/for node”的错误。这可能是由于配置冲突或版本不兼容引起的，需要检查构建工具和Vue的版本，并确保配置正确。
组件不渲染问题
设置isCustomElement后，可能会导致某些组件不渲染。这可能是因为将正常的Vue组件误判为自定义元素，需要仔细检查自定义元素的判断逻辑。
配置无效
如果配置后仍然出现组件解析失败的错误，可能是配置文件未正确加载或配置项书写错误，需要检查配置文件的路径和语法。