Farm 中使用社区插件:Vite/Rollup/unplugin 插件的兼容适配与配置实战
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 的buildStartresolveId→ Farm 的resolveload→ Farm 的loadtransform→ Farm 的transformbuildEnd→ Farm 的buildEndhandleHotUpdate→ Farm 的updateModulesrenderChunk→ Farm 的processRenderedResourcePotaugmentChunkHash→ Farm 的augmentResourcePotHashgenerateBundle→ Farm 的finalizeResourcestransformIndexHtml→ Farm 的transformHtmlwriteBundle/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 项目迁移时的核心动作:
- 将
vite.config.ts重命名为farm.config.ts,改用@farmfe/core的defineConfig; - 把原来放在
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()],
});
- 删除 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 中运行。