Farm 从 Vite 迁移实战指南:配置、插件兼容与验证
Farm 从 Vite 迁移实战指南:配置、插件兼容与验证
导读
本指南以 Farm 官方迁移文档 为骨架,系统讲解如何将一个 Vite 项目迁移到 Rust 编写的 Farm 构建工具。Farm 支持大量 Vite 风格的项目约定,但并非每个 Vite 内部 API 的"即插即用"替代品,迁移本质上是一次配置文件与插件兼容性的梳理过程。读完本文,你将掌握:配置文件重命名与字段映射、Vite 插件迁移到 vitePlugins 的正确姿势、Vite 专属配置项的替换清单,以及一套可复用的"先验证、再逐个恢复插件"的迁移排查流程。
1. 重命名配置文件
迁移的第一步是把 vite.config.ts 重命名为 farm.config.ts,并改用 Farm 的 defineConfig 帮助函数:
import { defineConfig } from '@farmfe/core';
export default defineConfig({
// Farm config
});
为什么是
defineConfig? 在 packages/core/src/index.ts 中,defineConfig实际是defineFarmConfig的别名导出,用于提供完整的 TypeScript 类型提示与配置校验。
Farm 配置文件解析顺序
Farm 会在项目根目录按固定顺序查找第一个命中的配置文件(详见 Configuring Farm):
farm.config.ts → farm.config.js → farm.config.cjs → farm.config.mjs → farm.config.cts → farm.config.mts
Farm 原生支持 TypeScript 配置文件:加载时会先将配置文件及其本地依赖打包到 node_modules/.farm/,再导入生成的产物,因此你在配置里可以放心使用 __dirname、__filename,ESM 配置文件也支持 import.meta.url。
配置文件的导出形式非常灵活——可以是对象、Promise,也可以是接收 { mode, command, isPreview } 的函数:
import { defineConfig } from '@farmfe/core';
export default defineConfig(({ mode, command }) => ({
compilation: {
mode,
},
}));
如果你偏好纯 JS 配置文件,也可以用 farm.config.mjs / farm.config.cjs 配合 JSDoc 获得编辑器类型支持:
/**
* @type {import('@farmfe/core').UserConfig}
*/
export default {
// ...
}
配置校验须知
Farm 在启动前会对配置做校验,未知字段会被直接拒绝。因此迁移时应优先使用文档化的 UserConfig 结构(compilation、server、plugins 等顶层字段),而不是把 Vite 内部字段原样塞给编译器。想要了解当前 Farm 全部配置字段,请查阅 Compiler Options、Dev Server Options 与 Shared Options。
2. 将 Vite 插件迁移到 vitePlugins
Farm 的原生插件放在 plugins 字段中,而 Vite 兼容插件必须放在 vitePlugins 字段,两者可以共存于同一份配置:
import { defineConfig } from '@farmfe/core';
import vue from '@vitejs/plugin-vue';
import sass from '@farmfe/plugin-sass';
export default defineConfig({
vitePlugins: [vue()],
plugins: [sass()]
});
上面的示例展示了混合使用方式:Vue 的 SFC 编译继续交给 Vite 生态的 @vitejs/plugin-vue,而 Sass 处理则改用 Farm 官方原生插件 @farmfe/plugin-sass,从而获得更好的性能与兼容性。
源码视角:vitePlugins 如何被处理
从源码看,Farm 对 Vite 插件的兼容是显式的、有损的:
- 在 packages/core/src/plugin/js/index.ts 的
handleVitePlugins中,Farm 会拉平异步插件、收集filters,并通过VitePluginAdapter把每个 Vite 插件适配为 Farm 的 JS 插件;只要vitePlugins非空,还会自动追加一个兼容用的默认 load 插件以及 CSS 包装/解包插件。 - 在 packages/core/src/plugin/js/farm-to-vite-config.ts 中,Farm 会把自身配置映射为一份 "Vite 视角" 的配置(
base、resolve.alias、server、build等)供 Vite 插件读取;而在 proxyViteConfig 里,Vite 插件能访问的viteConfig字段被白名单代理限定,越界的字段访问会触发不兼容告警,例如optimizeDeps的任意选项都会被忽略并打印警告。 - 在 packages/core/src/config/schema.ts 中,
vitePlugins被声明为可选的任意对象数组。
一句话结论:
vitePlugins提供的是"尽力而为"的适配层,而不是完整的 Vite 运行时模拟。这一点决定了迁移策略——不要把关键构建逻辑押注在深度耦合 Vite 内部实现的插件上。
用 filters 提升 Vite 插件性能
Farm 的 JS 插件钩子执行开销较高,官方建议为 Vite 插件声明 filters 正则,让不匹配的模块完全不进入 JS 插件钩子,从而在 Rust 侧并发安全地处理它们(默认过滤器为 <a href="https://link.gitcode.com/i/6ef9a21e8649cf76ca47042a67682d12" target="_blank">'!node_modules'],见 [packages/core/src/plugin/js/utils.ts):
import vue from '@vitejs/plugin-vue';
// Vite 插件的函数式写法:返回插件本体 + filters
function configureVitePluginVue() {
return {
vitePlugin: vue(),
// 只有命中这些规则的模块才会触发 JS 插件钩子
filters: ['\\.vue$', '\\\\0.+']
};
}
export default defineConfig({
vitePlugins: [configureVitePluginVue]
});
兼容性边界:哪些插件可以放心迁移
有些 Vite 插件依赖 Vite 内部机制,在 Farm 中可能无法正常工作。当插件与 Vite 深度耦合时,应优先改用:
- Farm 官方插件(如
@farmfe/plugin-sass、@farmfe/plugin-react等,参见 使用 Farm 插件); - PostCSS 插件(针对样式处理链路);
- 框架特定集成方案(如 Vue 用
@vitejs/plugin-vue、Solid 用vite-plugin-solid)。
仓库中也有大量真实示例可参考,例如 examples/preact/farm.config.ts 就同时使用了 @farmfe/plugin-react(原生 plugins)与 @preact/preset-vite(vitePlugins);examples/rust-plugin-auto-import-vue/farm.config.ts、examples/rust-plugin-modular-import/farm.config.ts 等示例则展示了 unplugin 生态插件(如 unplugin-auto-import、unplugin-vue-components)通过 vitePlugins 接入的方式(详见 Community Plugins)。
3. 移除 Vite 专属配置项
Farm 的架构与 Vite 不同,很多 Vite 的优化类配置项在 Farm 中根本不需要。迁移时应先删除 Vite 专属字段(典型如 optimizeDeps),只在确实需要时再添加 Farm 的等价配置。
常见替换对照表
| Vite 模式 | Farm 处理方式 |
|---|---|
plugins(用于 Vite 插件) |
移到 vitePlugins。 |
| 资源 / base 路径 | 使用 compilation.output.publicPath 或 CLI --base。 |
开发服务器配置(server.*) |
使用 Farm 的 server 字段(v2 起由 devServer 更名为 server)。 |
| Vite 专属 SSR 配置 | 参考 Farm SSR。 |
publicPath 与 --base 的实际用法
资源加载前缀在 Farm 中由 compilation.output.publicPath 控制(默认 "/",详见 Compiler Options),支持生产/开发环境的动态切换:
import { defineConfig } from '@farmfe/core';
export default defineConfig({
compilation: {
input: {
index: './src/index.html',
about: './src/about.html',
},
output: {
path: 'build',
publicPath: process.env.NODE_ENV === 'production' ? 'https://my-cdn.com' : '/'
}
},
});
也可以在命令行直接覆盖 base 路径(见 CLI API):
farm build --base /my-app/
开发服务器配置迁移
Farm 的 server 字段覆盖了 port、host、hmr、proxy、open、strictPort、https 等常用能力。一个典型的端口配置:
import { defineConfig } from '@farmfe/core';
export default defineConfig({
server: {
port: 9801
}
});
如果你此前用的是 Farm v1,注意 v2 已将
devServer重命名为server,并将spa布尔值改为appType: 'spa' | 'mpa' | 'custom',详见 v1 迁移 v2 指南。
按需关闭默认优化
Farm 默认开启树摇、压缩、持久缓存、懒编译等优化;若你在对比行为差异,可以显式关闭它们:
import { defineConfig } from '@farmfe/core';
export default defineConfig({
compilation: {
lazyCompilation: false,
persistentCache: false,
minify: false,
treeShaking: false
},
});
4. 验证迁移结果
同时跑通开发与生产构建
npx farm dev
npx farm build
其中 farm dev(别名 farm start)启动开发服务器并开启 HMR,farm build 产出生产构建。此外 Farm CLI 还提供 farm watch(开发模式编译 + 文件变更重建)、farm preview(本地预览生产产物)与 farm clean(清理持久缓存)等命令,完整选项见 CLI API。
迁移失败的排查策略
如果某个 Vite 插件在迁移过程中报错,先临时移除该插件,再把集成逐个加回来,这样就能把"配置本身的问题"与"插件兼容性问题"区分开:
- 删除出问题的插件后重新
farm build,确认构建恢复; - 逐个重新添加插件并重新构建,定位到具体是哪一个插件不兼容;
- 对该插件采取替代方案:换 Farm 官方插件、换 PostCSS 插件,或换框架特定集成;
- 结合浏览器控制台与终端日志,检查是否有
viteConfig越界字段的兼容性警告(对应源码中logCompatibilityWarning的告警路径)。
参考真实迁移案例
Farm 团队曾将真实的 Vite Admin 项目(farm-soybean-admin)完整迁移到 Farm,可将其作为实际迁移模式的参考范本。仓库内的 examples 目录同样提供了大量可运行的迁移样例——例如 examples/react-query/farm.config.ts、examples/solid-ssr/farm.config.mjs 等,均展示了 vitePlugins 与原生 plugins 的搭配用法,可以直接对照学习。
总结
从 Vite 迁移到 Farm 的完整路径可以概括为四步:重命名配置文件并引入 defineConfig → 把 Vite 插件移入 vitePlugins(原生插件留在 plugins)→ 删除 optimizeDeps 等 Vite 专属字段并替换为 Farm 等价配置 → 用 farm dev / farm build 验证并逐个恢复插件。核心原则是:把这次迁移当作"配置与插件兼容性的一次性梳理",而非逐行对照重写;对深度依赖 Vite 内部实现的插件,果断切换到 Farm 官方插件或 PostCSS 等更通用的方案,才能最大化迁移后的稳定性与构建性能。
延伸阅读
- 配置 Farm:配置文件解析顺序、TS 配置加载与校验规则
- 编译选项:
compilation字段全量参考 - 共享选项:
plugins、vitePlugins、mode、watch等顶层字段说明 - 使用 Farm 插件:JS 插件
filters机制与 unplugin 接入方式 - Farm v1 迁移 v2 指南:v2 破坏性变更与配置迁移对照
- Farm CLI:全部命令与全局选项