Vite 7.0 引入的几个重要新 API 详解

🚀 概述

Vite 7.0 引入了多个重要的新 API 和功能增强，主要包括 Environment API 的改进、Rolldown 集成、以及新的构建配置选项。本文档重点介绍这些新 API 的使用方法和实际应用场景。

🆕 新 API 特性

1. build.target 新默认值 API

作用：提供更现代的浏览器兼容性目标，基于 Web 标准的 Baseline 规范。

API 变更：

// vite.config.js
export default {
  build: {
    // 新默认值
    target: "baseline-widely-available",

    // 自定义配置
    target: ["chrome107", "firefox104", "safari16"],

    // 保持旧行为
    target: "modules",
  },
};

使用场景：

• 现代 Web 应用开发
• 需要使用最新 Web API 的项目
• 追求更好性能和更小包体积的应用

2. Environment API 增强

作用：提供多环境构建支持，允许在同一个 Vite 项目中配置不同的运行环境（如客户端、服务端、Worker 等）。

2.1 buildApp 钩子 API

新增功能：允许插件协调多环境构建过程。

API 使用：

// 插件中使用 buildApp 钩子
export function myPlugin() {
  return {
    name: "my-plugin",
    buildApp: async (builder) => {
      // 获取所有环境
      const environments = Object.values(builder.environments);

      // 串行构建
      for (const env of environments) {
        await builder.build(env);
      }

      // 或并行构建
      return Promise.all(environments.map((env) => builder.build(env)));
    },
  };
}

使用场景：

• 多环境应用（SSR + 客户端）
• 微前端架构
• 需要协调构建顺序的复杂项目

2.2 RunnableDevEnvironment API

作用：提供在开发环境中运行模块的能力，支持 HMR。

API 使用：

import { createServer, isRunnableDevEnvironment } from "vite";

const server = await createServer({
  environments: {
    ssr: {
      // SSR 环境配置
    },
  },
});

// 检查环境类型
if (isRunnableDevEnvironment(server.environments.ssr)) {
  // 动态导入模块
  const { render } = await server.environments.ssr.runner.import(
    "/src/entry-server.js"
  );

  // 执行服务端渲染
  const html = await render(url);
}

使用场景：

• SSR 开发环境
• 服务端 API 开发
• 需要在开发时执行 Node.js 代码的场景

3. Rolldown 集成 API

作用：基于 Rust 的高性能打包器，提供比传统 JavaScript 打包器更快的构建速度。

3.1 rolldown-vite 包使用

API 使用：

// package.json - 直接替换
{
  "dependencies": {
    "vite": "npm:rolldown-vite@latest"
  }
}

// package.json - 使用 overrides
{
  "overrides": {
    "vite": "npm:rolldown-vite@latest"
  }
}

3.2 advancedChunks API

新功能：替代 manualChunks，提供更精细的代码分割控制。

API 使用：

// vite.config.js
export default {
  build: {
    rollupOptions: {
      output: {
        // 新的 advancedChunks API
        advancedChunks: {
          groups: [
            {
              name: "vendor",
              test: /\/react(?:-dom)?/,
              priority: 10,
            },
            {
              name: "utils",
              test: /\/src\/utils/,
              priority: 5,
            },
          ],
        },
      },
    },
  },
};

使用场景：

• 大型项目的代码分割优化
• 需要精确控制 chunk 生成的场景
• 提升构建性能的项目

3.3 withFilter API

新功能：优化插件性能，减少 Rust 和 JavaScript 运行时之间的通信开销。

API 使用：

import { withFilter, defineConfig } from "vite";
import svgr from "vite-plugin-svgr";

export default defineConfig({
  plugins: [
    // 使用 withFilter 包装器
    withFilter(
      svgr({
        // SVG 插件配置
      }),
      {
        load: { id: /\.svg\?react$/ },
        transform: { id: /\.svg$/ },
      }
    ),
  ],
});

使用场景：

• 提升插件执行性能
• 减少不必要的插件调用
• 优化大型项目的构建速度

3.4 experimental.enableNativePlugin API

新功能：启用基于 Rust 的原生插件，提供更好的性能。

API 使用：

// vite.config.js
export default {
  experimental: {
    enableNativePlugin: true,
  },
  // 其他配置...
};

使用场景：

• 追求极致构建性能
• 大型项目优化
• 实验性功能测试

4. FetchableDevEnvironment API

作用：通过 Fetch API 接口与不同运行时环境通信，支持更广泛的运行时。

API 使用：

import {
  createServer,
  createFetchableDevEnvironment,
  isFetchableDevEnvironment,
} from "vite";

const server = await createServer({
  environments: {
    worker: {
      dev: {
        createEnvironment(name, config) {
          return createFetchableDevEnvironment(name, config, {
            handleRequest(request) {
              // 处理 Request 并返回 Response
              return new Response("Hello from worker");
            },
          });
        },
      },
    },
  },
});

// 使用 FetchableDevEnvironment
if (isFetchableDevEnvironment(server.environments.worker)) {
  const response = await server.environments.worker.dispatchFetch(
    new Request("/api/hello")
  );
}

使用场景：

• Cloudflare Workers 开发
• Edge Runtime 应用
• 需要跨运行时通信的场景

5. transformWithOxc API

新功能：使用 Oxc 替代 esbuild 进行代码转换，提供更好的性能。

API 使用：

import { transformWithOxc } from "vite";

// 替代 transformWithEsbuild
const result = await transformWithOxc(code, {
  loader: "tsx",
  target: "es2020",
});

使用场景：

• 插件开发中的代码转换
• 自定义构建流程
• 性能敏感的转换操作

6. rolldownVersion 检测 API

新功能：检测当前是否使用 rolldown-vite。

API 使用：

import { rolldownVersion } from "vite";

// 方法 1：检查导出
if (rolldownVersion) {
  // 使用 rolldown-vite 特定逻辑
  console.log("Using rolldown-vite:", rolldownVersion);
}

// 方法 2：在插件中检查
const plugin = {
  name: "my-plugin",
  configResolved() {
    if (this.meta.rolldownVersion) {
      // rolldown-vite 特定行为
    } else {
      // 标准 vite 行为
    }
  },
};

使用场景：

• 插件兼容性处理
• 条件功能启用
• 性能优化选择

� 实际应用示例

多环境 SSR 应用

// vite.config.js
import { defineConfig } from "vite";

export default defineConfig({
  environments: {
    // 客户端环境
    client: {
      build: {
        outDir: "dist/client",
        rollupOptions: {
          input: "src/entry-client.js",
        },
      },
    },
    // 服务端环境
    server: {
      build: {
        outDir: "dist/server",
        rollupOptions: {
          input: "src/entry-server.js",
        },
      },
    },
  },
  plugins: [
    {
      name: "ssr-plugin",
      buildApp: async (builder) => {
        // 先构建客户端，再构建服务端
        await builder.build(builder.environments.client);
        await builder.build(builder.environments.server);
      },
    },
  ],
});

Cloudflare Workers 集成

// vite.config.js
import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
  plugins: [cloudflare()],
  environments: {
    worker: {
      dev: {
        createEnvironment(name, config) {
          return createFetchableDevEnvironment(name, config, {
            handleRequest(request) {
              // 处理 Worker 请求
              return fetch(request);
            },
          });
        },
      },
    },
  },
});

高性能构建配置

// vite.config.js
import { defineConfig, withFilter } from "vite";

export default defineConfig({
  // 使用 Rolldown
  build: {
    rollupOptions: {
      output: {
        advancedChunks: {
          groups: [
            { name: "vendor", test: /node_modules/ },
            { name: "common", test: /src\/shared/ },
          ],
        },
      },
    },
  },
  experimental: {
    enableNativePlugin: true,
  },
  plugins: [
    // 优化插件性能
    withFilter(myPlugin(), {
      transform: { id: /\.(ts|tsx)$/ },
    }),
  ],
});

常见问题解决

问题 1：构建目标警告

// ❌ 可能出现的警告
// Warning: build.target 'modules' is deprecated

// ✅ 解决方案
export default {
  build: {
    target: "baseline-widely-available", // 或指定具体版本
  },
};

问题 2：插件兼容性

// ❌ 某些插件可能不兼容
import { someOldPlugin } from "vite-plugin-old";

// ✅ 检查插件是否有更新版本
// 或寻找替代方案

问题 3：Rolldown 选项验证

// ❌ Rolldown 可能警告未知选项
export default {
  build: {
    rollupOptions: {
      output: {
        generatedCode: 'es2015' // 可能不被 Rolldown 支持
      }
    }
  }
}

// ✅ 使用条件配置
import { rolldownVersion } from 'vite'

export default {
  build: {
    rollupOptions: {
      output: rolldownVersion ? {
        // Rolldown 特定配置
      } : {
        // Rollup 特定配置
        generatedCode: 'es2015'
      }
    }
  }
}

这些新 API 为现代前端开发提供了更强大的工具链支持，特别是在多环境部署、性能优化和跨平台开发方面带来了显著改进。