Vue Element Plus X 部署后资源加载失败问题

🐞 Vue Element Plus X 部署后资源加载失败问题

问题描述

现象： 项目在本地开发环境运行正常，但打包部署到服务器后出现资源加载失败错误：

bash 复制代码

无法加载资源: node_modules/vue-element-plus-x/dist/wasm/DDgzITey.C15qx4Aw.js

影响： 导致 vue-element-plus-x 组件功能异常，页面无法正常渲染相关功能。

🔍 问题根因分析

1. WASM 资源预加载机制冲突

vue-element-plus-x 内部使用了 WASM 模块，包含预加载(preload)资源
Vite 在生产构建时，对这些动态导入的 WASM 资源处理不当
资源路径在服务器环境下解析错误，导致 404 错误

2. 代码分割策略问题

Vite 默认的代码分割策略没有正确处理包含 WASM 的第三方库
shiki 和 vue-element-plus-x 的依赖关系复杂，需要特殊处理

3. 依赖预构建缺失

开发环境下 Vite 会自动预构建依赖，但生产环境需要显式配置
缺少预构建配置导致运行时动态加载失败

✅ 解决方案

在 vite.config.ts 中添加以下配置：

typescript 复制代码

export default defineConfig({
  // 1. 依赖预构建配置 - 确保关键依赖被正确预构建
  optimizeDeps: {
    include: [
      "vue-element-plus-x", // 包含 WASM 的组件库
      "shiki", // 语法高亮库，可能与 vue-element-plus-x 有依赖关系
    ],
  },

  build: {
    rollupOptions: {
      output: {
        // 2. 统一资源命名规则 - 避免路径解析问题
        chunkFileNames: "js/[name]-[hash].js",
        entryFileNames: "js/[name]-[hash].js",
        assetFileNames: "assets/[name]-[hash].[ext]",

        // 3. 手动代码分割 - 将问题依赖独立打包
        manualChunks: (id) => {
          // 将 shiki 相关代码打包到独立 chunk
          if (id.includes("shiki")) {
            return "shiki";
          }
          // 将 vue-element-plus-x 相关代码打包到独立 chunk
          if (id.includes("vue-element-plus-x")) {
            return "vue-element-plus-x";
          }
        },
      },
    },
  },
});

🎯 解决原理

依赖预构建 ：通过 optimizeDeps.include 强制 Vite 预构建这些包含 WASM 的依赖，确保资源路径正确解析
独立代码分割 ：通过 manualChunks 将问题依赖打包到独立的 chunk 中，避免与其他代码混合导致的路径问题
统一资源命名：规范化输出文件的命名规则，确保服务器端能正确识别和加载资源

📝 最佳实践

对于包含 WASM、Web Workers 或其他特殊资源的第三方库，建议都加入 optimizeDeps.include
使用 manualChunks 将大型依赖或问题依赖独立打包，提高加载稳定性
在部署前务必测试生产构建，确保所有资源能正确加载

⚠️ 版本兼容性说明

Vite 5.x 和 6.x：存在 WASM 资源加载问题，需要按照上述配置方案处理
Vite 7.x：根据社区插件 vite-plugin-wasm 的支持范围（仅支持 Vite 2.x-6.x）2，推测 Vite 7.x 可能改进了 WASM 处理机制，但官方文档暂未明确说明具体修复内容
建议：无论使用哪个版本，建议保留上述配置以确保 WASM 资源正常加载