Vite 6 到 Vite 7 的迁移指南，常见问题和解决方案

🚀 概述

Vite 7.0 是一个相对平滑的升级，但仍有一些重要的变更需要注意。本指南将帮助您顺利从 Vite 6 迁移到 Vite 7，包含详细的示例和解决方案。

📋 迁移前检查清单

环境要求检查

# 检查 Node.js 版本
node --version

# Vite 7 要求：
# - Node.js 20.19+ 或 22.12+
# - 不再支持 Node.js 18

🔄 核心变更和迁移步骤

1. 升级 Vite 版本

# npm
npm install vite@^7.0.0

2. 浏览器目标变更

变更说明：默认 build.target 从 'modules' 改为 'baseline-widely-available'

影响的浏览器版本：

• Chrome: 87 → 107
• Edge: 88 → 107
• Firefox: 78 → 104
• Safari: 14.0 → 16.0

迁移示例：

// ❌ Vite 6 默认行为
export default {
  build: {
    target: 'modules' // 旧默认值
  }
}

// ✅ Vite 7 新默认值
export default {
  build: {
    target: 'baseline-widely-available' // 新默认值
  }
}

// ✅ 如需保持旧行为
export default {
  build: {
    target: 'modules' // 显式指定
  }
}

// ✅ 自定义浏览器支持
export default {
  build: {
    target: ['chrome87', 'firefox78', 'safari14']
  }
}

3. 移除的功能

3.1 splitVendorChunkPlugin 已移除

问题：splitVendorChunkPlugin 在 Vite 7 中被移除

// ❌ Vite 6 中的用法（Vite 7 中不可用）
import { defineConfig, splitVendorChunkPlugin } from "vite";

export default defineConfig({
  plugins: [splitVendorChunkPlugin()],
});

解决方案：使用 manualChunks 替代

// ✅ Vite 7 替代方案
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          utils: ['lodash', 'axios']
        }
      }
    }
  }
})

// ✅ 或使用函数形式
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks(id) {
          if (id.includes('node_modules')) {
            if (id.includes('react')) {
              return 'react-vendor';
            }
            return 'vendor';
          }
        }
      }
    }
  }
})

3.2 Sass Legacy API 支持移除

问题：不再支持 Sass 的 legacy API

// ❌ Vite 6 中可能的配置（Vite 7 中不支持）
export default {
  css: {
    preprocessorOptions: {
      sass: {
        api: "legacy", // 已移除
      },
    },
  },
};

解决方案：使用现代 Sass API

// ✅ Vite 7 推荐配置
export default {
  css: {
    preprocessorOptions: {
      sass: {
        api: "modern", // 或省略此选项（默认为 modern）
        silenceDeprecations: ["legacy-js-api"],
      },
    },
  },
};

4. 插件兼容性更新

4.1 常用插件升级

# React 插件
npm install @vitejs/plugin-react@^4.0.0

# Vue 插件
npm install @vitejs/plugin-vue@^5.0.0

# Vitest（如果使用）
npm install vitest@^3.2.0

# 检查其他插件兼容性
npm outdated

4.2 插件配置更新示例

// vite.config.js
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [
    react({
      // React 插件配置保持不变
    }),
    vue({
      // Vue 插件配置保持不变
    }),
  ],
});

5. ESM-only 分发适配

变更说明：Vite 7 完全以 ESM 模块形式分发

// ✅ 推荐：使用 ESM 导入
import { defineConfig } from "vite";

// ✅ 仍然支持（在 Node.js 20.19+/22.12+ 中）
const { defineConfig } = require("vite");

// ❌ 在旧版本 Node.js 中不再支持

package.json 更新建议：

{
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

🔧 可选的性能优化

1. 尝试 Rolldown（实验性）

// package.json - 体验 Rolldown 性能提升
{
  "dependencies": {
    "vite": "npm:rolldown-vite@latest"
  }
}

// 或使用 overrides
{
  "overrides": {
    "vite": "npm:rolldown-vite@latest"
  }
}

2. Environment API 配置（可选）

// vite.config.js - 多环境配置
export default defineConfig({
  environments: {
    client: {
      build: {
        outDir: "dist/client",
      },
    },
    server: {
      build: {
        outDir: "dist/server",
      },
    },
  },
});

⚠️ 常见问题和解决方案

1. 构建目标警告

问题：看到关于 build.target 的警告

Warning: build.target 'modules' is deprecated

解决方案：

// vite.config.js
export default {
  build: {
    target: "baseline-widely-available", // 使用新默认值
    // 或指定具体版本以保持兼容性
    // target: ['chrome87', 'firefox78', 'safari14']
  },
};

2. 插件不兼容

问题：某些第三方插件可能不兼容

解决方案：

# 检查插件更新
npm outdated

# 更新到兼容版本
npm update

# 或寻找替代插件

3. TypeScript 配置

更新 tsconfig.json（如需要）：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

🚨 故障排除指南

1. 依赖冲突解决

# 清理依赖
rm -rf node_modules package-lock.json
npm install

# 检查依赖树
npm ls vite

# 解决版本冲突
npm install --force

2. 构建错误处理

常见错误及解决方案：

// 错误：Module not found
// 解决：检查导入路径
import { defineConfig } from "vite"; // ✅ 正确
// import { defineConfig } from 'vite/config' // ❌ 可能出错

// 错误：Target environment "modules" is deprecated
// 解决：更新构建目标
export default {
  build: {
    target: "baseline-widely-available", // ✅
  },
};

3. 性能问题诊断

// vite.config.js - 性能调试配置
export default defineConfig({
  build: {
    // 启用构建分析
    rollupOptions: {
      output: {
        manualChunks(id) {
          // 调试代码分割
          console.log("Chunk ID:", id);
          if (id.includes("node_modules")) {
            return "vendor";
          }
        },
      },
    },
  },

  // 开发服务器优化
  server: {
    fs: {
      strict: false,
    },
  },
});

---

总结：Vite 7 的迁移相对简单，主要注意 Node.js 版本要求、浏览器目标变更和已移除功能的替代方案。通过本指南的分步骤迁移，大多数项目可以平滑升级，享受更好的性能和新功能。记住在迁移过程中做好备份和测试，确保应用的稳定性。