Farm 中使用社区插件:Vite/Rollup/unplugin 插件的兼容适配与配置实战

原创2026-10-13 12:50:351,982 阅读
文章标签:前端构建构建工具开发工具插件系统前端WebAssembly

Farm 中使用社区插件:Vite/Rollup/unplugin 插件的兼容适配与配置实战

Farm 作为一款用 Rust 编写的 Vite 兼容构建工具,天生支持直接复用 Vite/Rollup 以及 unplugin 生态中的海量社区插件。本文围绕 vitePlugins 配置项,系统讲解如何在 farm.config.ts 中接入 Vue、Solid、mock、自动导入、UI 组件按需加载等社区插件,并结合源码剖析其兼容适配原理、filters 性能优化机制与兼容性边界,帮助你在不重写插件的前提下完成从 Vite 到 Farm 的平滑迁移。

一、开箱即用:Farm 对 Vite/Rollup/unplugin 生态的支持

Farm 的核心编译管线由 Rust 实现,但为了兼容当前 JS 生态,它提供了一个插件适配层:vitePlugins。凡是遵循 Vite/Rollup 插件接口、或者基于 unplugin 规范编写的插件,都可以不加改动地直接放进 Farm 的配置中使用,这就是"开箱即用(out of box)"的含义。

不过官方文档同时给出了明确建议:Farm 优先推荐编写 Farm 原生插件(plugins 配置项),而非直接使用 Vite/Rollup 插件,因为 Farm 原生插件具备最好的兼容性和性能。如果你开发了兼容 Farm 的插件并希望收录进官方列表,也可以通过 PR 贡献。

从配置类型定义可以看到 vitePlugins 的完整形态(packages/core/src/config/types.ts):

vitePlugins?: (
  | null
  | undefined
  | object
  | (() => { vitePlugin: any; filters: string[] })
)[];

即 vitePlugins 数组中的每一项既可以是插件对象本身,也可以是一个返回 { vitePlugin, filters } 的函数(后者用于指定性能过滤器,见下文第三节)。该配置项默认值为 <a href="https://link.gitcode.com/i/5a9cebcffe60565b17197e49425ed670" target="_blank">],具体说明可参考 [配置文档。

二、在 farm.config.ts 中接入 Vite/Rollup 插件

2.1 基本用法

通过 vitePlugins 配置即可使用 Vite/Rollup 插件。官方文档给出的最小示例:

import { UserConfig } from "@farmfe/core";
import vue from "@vitejs/plugin-vue";
import vueJsx from "@vitejs/plugin-vue-jsx";

const config: UserConfig = {
  vitePlugins: [vue(), vueJsx()],
};

@vitejs/plugin-vue 提供 Vue SFC 编译支持,@vitejs/plugin-vue-jsx 提供 Vue JSX/TSX 支持。两者是 Farm 上最常用的 Vite 插件组合,仓库内的 vue3 示例 正是以 vitePlugins: [Vue()] 的方式接入 Vue:

import { defineConfig } from "@farmfe/core";
import Vue from "@vitejs/plugin-vue";

export default defineConfig({
  vitePlugins: [Vue()],
  compilation: {
    progress: false,
    persistentCache: false,
  },
});

值得注意的是,该示例顶部还注释了两行 import Vue from "unplugin-vue/farm" 与 import Vue from "unplugin-vue/vite",说明同一份 Vue 插件既可以用 unplugin 的产物,也可以用 @vitejs/plugin-vue 的产物,具体选择取决于你的依赖习惯。

2.2 常用社区插件清单

官方文档收录了以下几类可直接使用的 Vite/Rollup 插件:

  • @vitejs/plugin-vue:Vue 单文件组件(SFC)支持;
  • @vitejs/plugin-vue-jsx:Vue JSX/TSX 支持;
  • vite-plugin-solid:Solid 框架支持。Solid 官方集成文档(website/docs/frameworks/solid.mdx)明确推荐通过 vitePlugins 使用 vite-plugin-solid,且配合 filters 限定只处理 .tsx/.jsx 文件(见第三节);
  • vite-plugin-mock:在开发与生产环境同时提供 mock 数据能力;
  • 更多插件通过 ... 持续扩充,凡遵循 Vite/Rollup 接口的插件都可尝试接入。

2.3 结合源码理解适配原理

为什么 Vite 插件能在 Farm 中直接运行?关键在 packages/core/src/plugin/js/index.ts 的 handleVitePlugins 函数:它会遍历 vitePlugins 数组,将每个 Vite 插件交给 VitePluginAdapter 封装成 Farm JS 插件,再注入编译管线(见 handleVitePlugins 实现)。

VitePluginAdapter(packages/core/src/plugin/js/vite-plugin-adapter.ts)完成的是"钩子翻译"工作,它维护了一张 Vite 钩子到 Farm 钩子的映射表,例如:

  • buildStart → Farm 的 buildStart
  • resolveId → Farm 的 resolve
  • load → Farm 的 load
  • transform → Farm 的 transform
  • buildEnd → Farm 的 buildEnd
  • handleHotUpdate → Farm 的 updateModules
  • renderChunk → Farm 的 processRenderedResourcePot
  • augmentChunkHash → Farm 的 augmentResourcePotHash
  • generateBundle → Farm 的 finalizeResources
  • transformIndexHtml → Farm 的 transformHtml
  • writeBundle/closeBundle → Farm 的 writeResources

同时,适配层还负责 Vite 配置与 Farm 配置之间的双向转换(farm-to-vite-config.ts):farmUserConfigToViteConfig 把 Farm 的 root、base、publicDir、mode、define、resolve.alias、server、build 等配置翻译成 Vite 插件能识别的 viteConfig;插件执行 config 钩子改写了配置后,再由 viteConfigToFarmConfig 把改动映射回 Farm 配置。此外,插件拿到的 viteConfig 其实是一个 Proxy(proxyViteConfig),只暴露白名单内的字段,超出范围访问会触发兼容性报错,避免插件悄悄依赖 Farm 未提供的 Vite 内部状态。

如果插件使用了 Farm 不支持的 Vite 钩子(如 moduleParsed、renderError、resolveDynamicImport、resolveFileUrl、resolveImportMeta、banner、footer),适配层会发出兼容性警告而非静默吞掉。

三、filters:函数式语法与性能优化

默认情况下,每个 Vite 插件的过滤器取 DEFAULT_FILTERS = <a href="https://link.gitcode.com/i/b588c69d6c3f7837f03bffbf354c8229" target="_blank">'!node_modules'](见 [packages/core/src/plugin/js/utils.ts),即默认跳过 node_modules 目录下的模块,以减小 JS 插件的执行开销。

为进一步提升性能,vitePlugins 支持函数式语法:把插件包装成一个返回 { vitePlugin, filters } 的函数,filters 用正则字符串限定插件需要处理的模块路径,未匹配的模块会直接跳过,完全不触发该插件。例如 Solid 官方推荐配置:

import { defineConfig } from '@farmfe/core';
import solid from 'vite-plugin-solid';

export default defineConfig({
  vitePlugins: [
    () => ({
      vitePlugin: solid(),
      filters: ['\\.tsx$', '\\.jsx$']
    })
  ]
});

仓库内的 vite-adapter-vue 示例 提供了更复杂的过滤写法,支持 ! 前缀排除规则与精确路径白名单的组合:

function configureVitePluginVue() {
  return {
    vitePlugin: vue(),
    // 未匹配的模块路径将被跳过
    filters: ["!node_modules", "node_modules/my-ui"],
  };
}

export default defineConfig({
  vitePlugins: [
    configureVitePluginVue,
    vueJsx(),
    // ...
  ],
});

从源码看,handleVitePlugins 会合并所有过滤器到 filtersUnion,并额外注入一个默认 load 插件与 CSS 包装/解包插件以保证与 Vite 加载语义的兼容(见 packages/core/src/plugin/js/index.ts)。合理设置 filters 能让大部分模块在纯 Rust 侧并发处理,避免进入慢速的 JS 插件路径,这也是"Vite 插件能跑、但要跑得尽量快"的关键手段。

四、unplugin 插件:一套代码,三种入口

unplugin 是 antfu 发起的"编译引擎无关"插件规范,同一份插件源码可以编译输出针对 Vite、Rollup、Webpack、esbuild 等多个入口的产物。Farm 官方声明:unplugin/farm、unplugin/vite、unplugin/rollup 三种入口目前均可直接使用。如果使用 unplugin/vite 或 unplugin/rollup 时发现部分属性尚未完全适配,或团队认为某 API 不具备适配条件,可以到 Farm 仓库提交 issue 反馈。

由于 unplugin 插件最终仍是标准的 Vite/Rollup 插件形态,因此在 Farm 中统一放进 vitePlugins 数组即可。官方文档给出的完整示例(Icons 图标自动加载 + 组件自动注册):

import Icons from "unplugin-icons/vite";
import IconsResolver from "unplugin-icons/resolver";
import Components from "unplugin-vue-components/rollup";
import { NaiveUiResolver } from "unplugin-vue-components/resolvers";
import { FileSystemIconLoader } from "unplugin-icons/loaders";

const config: UserConfig = {
  vitePlugins: [
    Icons({
      compiler: "vue3",
      customCollections: {
        [collectionName]: FileSystemIconLoader(localIconPath, (svg) =>
          svg.replace(/^<svg\s/, '<svg width="1em" height="1em" ')
        ),
      },
      scale: 1,
      defaultClass: "inline-block",
    }),
    Components({
      dts: "src/typings/components.d.ts",
      types: [{ from: "vue-router", names: ["RouterLink", "RouterView"] }],
      resolvers: [
        NaiveUiResolver(),
        IconsResolver({
          customCollections: [collectionName],
          componentPrefix: VITE_ICON_PREFIX,
        }),
      ],
    }),
  ],
};

上述配置中的关键参数说明:

  • Icons({ compiler: "vue3", ... }):compiler 指定图标组件生成的模板框架(vue3/vue2/jsx 等);customCollections 注册自定义图标集合,FileSystemIconLoader 从本地目录读取 SVG 文件,并通过回调改写 SVG 根节点属性(示例中统一注入 width="1em" height="1em" 使图标随字体大小缩放);scale 控制图标缩放倍率;defaultClass 为生成的图标组件附加默认类名。
  • Components({ dts: "src/typings/components.d.ts", ... }):dts 指定自动生成的组件类型声明文件路径;types 声明需要全局注册的非组件类型(如 vue-router 的 RouterLink/RouterView);resolvers 数组按顺序尝试解析组件来源,NaiveUiResolver 负责 Naive UI 组件按需引入,IconsResolver 配合 customCollections 与 componentPrefix 把 <prefix-xxx> 形式的模板标签解析为对应图标。

unplugin-auto-import 与 unplugin-vue-components 是另外一对高频组合,vite-adapter-vue 示例 中配合 Element Plus 的写法:

import AutoImport from 'unplugin-auto-import/vite';
import Components from 'unplugin-vue-components/vite';
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers';

export default defineConfig({
  vitePlugins: [
    AutoImport({
      resolvers: [ElementPlusResolver({ importStyle: 'sass' })],
      imports: ['vue', VueRouterAutoImports],
    }),
    Components({
      resolvers: [ElementPlusResolver({ importStyle: 'sass' })],
    }),
  ],
});

importStyle: 'sass' 让 Element Plus 组件按需引入样式(scss 源文件),AutoImport 的 imports 数组还能额外纳入 unplugin-vue-router 提供的自动导入集合。

unplugin 生态兼容清单

官方文档声明"所有 unplugin 插件均受支持",并给出了经过验证的清单(以下插件均按上述 vitePlugins 方式接入):

  • unplugin-auto-import:API 自动导入;
  • unplugin-vue2-script-setup:Vue 2 <script setup> 支持;
  • unplugin-icons:图标按需引入;
  • unplugin-vue-components:Vue 组件按需自动注册;
  • unplugin-upload-cdn:上传资源到 CDN;
  • unplugin-web-ext:浏览器扩展(Web Extension)构建支持;
  • unplugin-properties:读取 properties 配置文件;
  • unplugin-moment-to-dayjs:moment 到 dayjs 的迁移替换;
  • unplugin-object-3d:3D 对象模型支持;
  • unplugin-parcel-css:接入 parcel-css 处理 CSS;
  • unplugin-vue:unplugin 版的 Vue 编译插件;
  • unplugin-vue-macros:Vue 宏语法扩展;
  • unplugin-vue-define-options:defineOptions 宏(vue-macros 子包);
  • unplugin-jsx-string:JSX 字符串渲染支持;
  • unplugin-ast:AST 级代码转换;
  • unplugin-element-plus:Element Plus 按需引入;
  • unplugin-glob:glob 导入语法支持;
  • unplugin-sentry:Sentry 错误监控集成;
  • unplugin-imagemin:图片压缩;
  • unplugin-typedotenv:环境变量类型化(typed dotenv);
  • unplugin-fonts:字体资源处理;
  • sentry-javascript-bundler-plugins:Sentry JS bundler 插件系列;
  • unplugin-svg-component:SVG 组件化;
  • unplugin-vue-cssvars:Vue 组件 CSS 变量提取。

五、迁移视角:从 Vite 项目平滑切换到 Farm

官方迁移指南(website/docs/migration/from-vite.md)给出了从 Vite 项目迁移时的核心动作:

  1. 将 vite.config.ts 重命名为 farm.config.ts,改用 @farmfe/core 的 defineConfig;
  2. 把原来放在 plugins 里的 Vite 插件移到 vitePlugins,Farm 原生插件继续放在 plugins:
import { defineConfig } from '@farmfe/core';
import vue from '@vitejs/plugin-vue';
import sass from '@farmfe/plugin-sass';

export default defineConfig({
  vitePlugins: [vue()],
  plugins: [sass()],
});
  1. 删除 Vite 特有、Farm 不需要的优化选项(如 optimizeDeps,Farm 无依赖预构建概念),仅在实际需要时补充 Farm 等价配置。

仓库内的 vite-adapter-react 示例 展示了"原生插件 + Vite 插件"混用的典型形态:React 编译走 Farm 原生 Rust 插件 @farmfe/plugin-react,而 vite-plugin-pages 这类 Vite 生态插件则放在 vitePlugins:

import { defineConfig } from '@farmfe/core';
import Pages from 'vite-plugin-pages';
import react from '@farmfe/plugin-react';

export default defineConfig({
  plugins: [react({ runtime: 'automatic', refresh: true })],
  compilation: { persistentCache: false },
  vitePlugins: [Pages({ resolver: 'react' })],
});

六、兼容性边界与实践建议

  • 适配层有明确白名单:Vite 插件能访问的 viteConfig、resolve、server、css、build 字段都是受控的(见 proxyViteConfig 白名单),optimizeDeps 等 Vite 专属选项在 Farm 中被明确忽略并给出提示;resolve.alias 中的 customResolver 不被支持,会被忽略并告警。
  • 未支持钩子会告警而非失败:使用 moduleParsed、renderError、resolveDynamicImport、resolveFileUrl、resolveImportMeta、banner、footer 等钩子的插件会收到兼容性警告,功能可能不完整。
  • 优先考虑 Farm 原生插件:对性能敏感或需要深度控制编译流程的场景,应优先选择 Farm 原生插件体系(Rust 插件性能最佳,JS 插件便于复用 JS 生态),vitePlugins 作为生态补充手段。
  • 善用 filters:给每个 Vite/unplugin 插件配置精确的 filters,让未匹配模块全部留在 Rust 侧并发处理,是保持 Farm 极致构建速度的关键。
  • 配置入口参考:vitePlugins 的默认值与语义说明可查阅 配置共享选项;更全面的插件体系总览可阅读 Using Plugins 文档。

综上所述,Farm 通过 vitePlugins 加一层轻量适配器,就完整接入了 Vite/Rollup/unplugin 三大插件生态:既能在迁移期零成本复用现有插件,又能通过 filters 函数语法和 Farm 原生插件逐步逼近最优性能。对于 Vue 全家桶、Solid、Element Plus/Naive UI 按需加载、图标自动注册、mock 数据等典型需求,本文给出的配置均可直接复制到 farm.config.ts 中运行。

登录后查看全文
farm