Vue3项目使用lottie-player出现无法解析组件及iOS Chrome异常问题求助

一、根治Vue组件解析警告 #

Vue3默认会将未注册的HTML标签视为Vue组件进行解析，lottie-player属于第三方自定义Web Components，需要主动配置让Vue跳过对该类标签的解析：

• Vite 项目配置
  在vite.config.js中添加如下配置：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // 将所有lottie开头的标签标记为自定义元素
          isCustomElement: tag => tag.startsWith('lottie-')
        }
      }
    })
  ]
})

• Vue CLI 项目配置
  在vue.config.js中添加如下配置：

module.exports = {
  chainWebpack: config => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap(options => {
        options.compilerOptions = {
          ...(options.compilerOptions || {}),
          isCustomElement: tag => tag.startsWith('lottie-')
        }
        return options
      })
  }
}

如果项目使用了自动导入组件的插件（如unplugin-vue-components），需要将lottie-player添加到插件的排除列表中，避免插件尝试匹配对应Vue组件。

二、修复iOS端Chrome兼容问题 #

iOS端Chrome无法正常加载lottie-player通常是Web Components注册时机或者低版本兼容问题，可按以下步骤排查修复：

1. 调整引入时机，在入口文件main.js顶部同步引入lottie-player，不要使用动态异步引入：

// main.js 最顶部添加
import '@lottiefiles/lottie-player'

2. 针对低版本iOS Chrome添加Web Components兼容polyfill：
   先安装依赖：npm install @webcomponents/webcomponentsjs，再在main.js最顶部引入polyfill：

import '@webcomponents/webcomponentsjs/webcomponents-bundle.js'
import '@lottiefiles/lottie-player'

3. 避免使用v-if控制lottie-player的显隐，替换为v-show，减少自定义元素的销毁重建操作，降低iOS端兼容问题概率。

三、替代方案（兼容性最优） #

如果以上配置后仍有兼容问题，可以直接使用lottie-web原生API封装Vue组件，完全绕开Web Components的兼容问题，无解析警告，全平台兼容：

<template>
  <div ref="lottieBox"></div>
</template>
<script setup>
import lottie from 'lottie-web'
import { ref, onMounted } from 'vue'

const lottieBox = ref(null)
onMounted(() => {
  lottie.loadAnimation({
    container: lottieBox.value,
    renderer: 'svg',
    loop: true,
    autoplay: true,
    path: '/你的动画文件路径.json' // 也可以直接传入json对象
  })
})
</script>

内容的提问来源于stack exchange，提问作者thomalex