Vue SSR项目使用Vite构建时导入jQuery出现Top-level await报错如何解决？

问题原因 #

你遇到的Top-level await报错是因为顶层 await 语法仅 ES2022 及以上标准支持，你之前配置的es2015~es2019都不包含该特性，且即使配置高版本target，部分SSR运行环境对顶层await的支持也不完善，更推荐调整引入逻辑解决。

可行解决方案 #

方案1：将引入逻辑放到客户端专属生命周期（最推荐） #

SSR 阶段不会执行客户端生命周期钩子，把动态引入逻辑放到这里既不会触发SSR构建错误，也不需要调整构建配置：

• 如果你用的是Vue/Nuxt框架，放到onMounted钩子中：

import { onMounted } from 'vue'

onMounted(async () => {
  // 仅客户端执行引入，jQuery已经通过index.html的script挂载到window，插件引入后直接挂载到全局$上
  await import('jquery-flexdatalist/jquery.flexdatalist')
  // 此处写插件初始化逻辑即可
})

• 如果你用的是React/Next框架，放到空依赖的useEffect钩子中：

import { useEffect } from 'react'

useEffect(() => {
  const initJqueryPlugin = async () => {
    await import('jquery-flexdatalist/jquery.flexdatalist')
    // 此处写插件初始化逻辑即可
  }
  initJqueryPlugin()
}, [])

方案2：配置Vite SSR忽略jQuery相关依赖 #

在vite.config.js中添加如下配置，让SSR构建阶段不处理jQuery相关的包，自然不会抛出引入错误：

export default defineConfig({
  ssr: {
    // 把所有jQuery相关的依赖都加到这个数组里即可
    external: ['jquery', 'jquery-flexdatalist']
  }
})

方案3：配置构建目标支持顶层await #

如果你确实需要使用顶层await写法，直接把构建目标调整为支持该语法的版本即可：

export default defineConfig({
  build: {
    target: 'es2022'
  }
})

注意：该方案会降低项目对旧版本浏览器的兼容性，优先推荐前两种方案。

额外注意事项 #

你已经通过index.html的script标签引入了jQuery主库，不要通过ESM再次引入jQuery，避免出现多份jQuery实例、插件挂载异常的问题，所有引入的jQuery插件都会自动挂载到全局的window.$对象上，直接使用即可。

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