如何将Vue 3 + Vite应用作为Widget嵌入第三方网站HTML文件？

一、先确保Widget项目构建出可复用的产物 #

1. 修改Vite配置文件（vite.config.js） #

要让Widget打包成通用库格式，而非单页应用：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue' // 以Vue为例，React/其他框架替换对应插件

export default defineConfig({
  plugins: [vue()],
  build: {
    lib: {
      entry: 'src/widget-entry.js', // 指定Widget的入口文件
      name: 'MyWidget', // 全局变量名（UMD格式用）
      formats: ['es', 'umd'], // 输出ES模块和UMD两种格式，覆盖不同场景
      fileName: (format) => `my-widget.${format}.js`
    },
    rollupOptions: {
      // 排除外部依赖（比如Vue），让宿主项目自行提供，避免重复打包
      external: ['vue'],
      output: {
        // 为外部依赖指定全局变量名（UMD格式下生效）
        globals: {
          vue: 'Vue'
        }
      }
    }
  }
})

2. 编写Widget入口文件（src/widget-entry.js） #

必须暴露挂载/销毁的API，让宿主项目能控制Widget的生命周期：

import { createApp } from 'vue'
import MyWidget from './components/MyWidget.vue'

// 暴露挂载方法：接收宿主容器元素和自定义配置
export function mountWidget(container, options = {}) {
  const app = createApp(MyWidget, options)
  app.mount(container)
  return app // 返回实例，方便后续销毁
}

// UMD格式兼容：允许通过全局变量直接调用
if (typeof window !== 'undefined') {
  window.MyWidget = { mountWidget }
}

3. 执行构建 #

运行命令生成产物：

npm run build

构建完成后，dist目录下会生成my-widget.es.js（ES模块）和my-widget.umd.js（UMD模块）。

二、独立项目接入Widget产物 #

方式1：script标签直接引入（适合纯HTML/非模块化项目） #

<!-- 先引入Widget依赖的全局库（比如Vue） -->
<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
<!-- 引入Widget的UMD产物 -->
<script src="./dist/my-widget.umd.js"></script>

<!-- 宿主页面中预留Widget容器 -->
<div id="widget-container"></div>

<script>
  // 挂载Widget，传入容器选择器和自定义配置
  const widgetInstance = window.MyWidget.mountWidget('#widget-container', {
    title: '自定义标题',
    apiUrl: '/api/xxx'
  })

  // 如需销毁Widget，调用实例的unmount方法
  // widgetInstance.unmount()
</script>

方式2：ES模块引入（适合Vite/Webpack等模块化项目） #

在独立项目的组件或JS文件中：

import { mountWidget } from '../path/to/my-widget.es.js'

// 在合适的生命周期钩子中挂载（以Vue为例）
onMounted(() => {
  const container = document.getElementById('widget-container')
  mountWidget(container, {
    title: '自定义标题'
  })
})

注意：如果Widget依赖Vue，需确保独立项目已安装对应版本的Vue：

npm install vue

三、常见问题排查 #

• 依赖冲突报错：检查Widget的Vite配置是否正确排除了外部依赖（比如external: ['vue']），避免把依赖打包进产物导致和宿主项目版本冲突。
• 无法找到挂载方法：确认Widget入口文件是否正确暴露了mountWidget等API，不要直接在入口文件中执行mount操作。
• 样式污染：Widget内部使用scoped样式（Vue）或CSS Modules，或者在Vite配置中开启build.cssCodeSplit，避免样式影响宿主项目。
• 路径错误：引入产物时确保路径正确，开发环境可使用绝对路径，生产环境注意静态资源的部署路径。

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