前言

大家好，我是倔强青铜三。作为一名对IT技术充满热情的软件工程师，我一直在寻找机会分享和传播我的知识和技能。今天，我想和大家分享一个对我来说既具挑战性又极具启发性的项目——从 Vue 2 到 Vue 3 的 Web 组件迁移之旅。

Vue 与 Web 组件

与常见的单页应用（SPA）不同，Open Library 并不通过 Vue 渲染整个应用，而是利用 Vue 在传统 HTML 页面中实现特定的交互元素。这通过集成自定义 HTML 标签（即 Web 组件）来实现，这些标签随后被转换为 Vue 组件。

例如，在 Open Library 页面的源代码中，你可能会看到 <ol-barcode-scanner> 标签。这个自定义标签及其 JavaScript 代码允许 Vue 仅渲染该特定元素，而不是管理整个页面。这就好比在传统的 HTML 页面中散布着一个个小型的 Vue 应用。

Vue 3 迁移挑战

尽管 Vue 3 与 Vue 2 大体兼容，且有许多资源可用于从 Vue 2 迁移到 Vue 3，但在构建 Vue 3 Web 组件时，我们面临了一些独特的挑战。

使用 Vite 构建单个 Web 组件

Vue CLI 已经不再支持 Vue 3 Web 组件，且多年来未更新。因此，我开始研究最新的构建工具：Vite。Vite 的一个主要区别在于它不接受 .vue 文件（单文件组件），而是需要一个配置文件作为输入。这带来了挑战，因为我需要为每个组件新增两个文件。

构建多个 Web 组件

此时，我们的 Vite 配置文件只能有一个输入，即一个 JavaScript 文件，它会生成一个输出，即所需的 JavaScript 文件。这一限制带来了挑战，因为我们有许多组件需要构建。虽然 Vite 配置文件支持多输入和多输出设置，但当我们使用 inlineDynamicImports 选项时，这一功能就不可用，而我们又需要这个选项来让组件独立工作。

试错过程

通过阅读文档、不断试错以及借助 ChatGPT，我们痛苦地接受了确实需要一个 Vue 文件、一个指向 Vue 文件的 JavaScript 文件，以及一个指向 JavaScript 文件的配置文件。如果我们按照传统方式处理，每个组件都需要一个 Vue 文件、一个 JavaScript 文件和一个 Vite 配置文件。目前我们有五个组件，这意味着我们需要新增十个几乎相同的文件。

解决方案

虽然这种方法看起来有些“黑客”风格，但它确实有效，而且没有在代码库中新增十个文件。它分为两部分：

1. 设置一个环境变量 COMPONENT_NAME，让 vite.config.js 读取它，这样我们就不需要为每个组件单独创建一个配置文件。
2. 我们需要处理这些烦人的输入文件。因此，我们直接在配置文件中从字符串生成它们。

具体实现如下：

const COMPONENT_NAME = process.env.COMPONENT;

export default defineConfig({
  build: {
    outDir: 'PRODUCTION_DIR',
    emptyOutDir: false,
    target: 'es2015',
    rollupOptions: {
      input: join(BUILD_DIR, `vue-tmp-${COMPONENT_NAME}.js`),
      output: {
        entryFileNames: `ol-${COMPONENT_NAME}.js`,
        inlineDynamicImports: true,
        format: 'iife'
      }
    }
  }
});

function generateViteEntryFile(componentName) {
  const template = `
import { defineCustomElement } from 'vue';
import ele from './${componentName}.vue';
customElements.define('${kebabCase(componentName)}', defineCustomElement(ele));
`;

  try {
    writeFileSync(join(BUILD_DIR, `vue-tmp-${componentName}.js`), template);
  } catch (error) {
    console.error(`Failed to generate Vite entry file: ${error.message}`);
    process.exit(1);
  }
}

总结

从 Vue 2 Web 组件迁移到 Vue 3 Web 组件的过程中，我遇到了许多挑战。但现在我们已经找到了解决方案，这些挑战似乎并不那么难了。我相信在迁移过程中遇到的困难是有技术原因的。

如果我有一根魔法棒，我希望做出以下改变：

1. Vite（底层使用 Rollup）应该允许在使用 inlineDynamicImports 的同时支持多输入和多输出。
2. Web 组件指南应该增加关于插件的信息。解释如何在不引入额外依赖的情况下添加插件，或者至少指出 vue-web-component-wrapper 是一个可行的解决方案。
3. Vite 应该能够在 vite.config.js 中直接接受 .vue 文件。

总的来说，这次迁移过程大约耗费了我 20 个小时（不包括前几年其他人的尝试）。在整个过程中，我没有找到一个能够涵盖所有这些挑战的示例。我希望这篇文章能对那些在 2025 年及以后从 Vue 2 迁移到 Vue 3 的开发者有所帮助。也许 Vue 和 Vite 团队会注意到这一点，并改进官方指南，甚至可能改进工具。

祝开源顺利！

欢迎关注我，微信公众号：倔强青铜三。欢迎点赞、收藏、关注，一键三连！！！