Farm 从 Vite 迁移实战指南:配置、插件兼容与验证

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

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 深度耦合时,应优先改用:

  1. Farm 官方插件(如 @farmfe/plugin-sass、@farmfe/plugin-react 等,参见 使用 Farm 插件);
  2. PostCSS 插件(针对样式处理链路);
  3. 框架特定集成方案(如 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 插件在迁移过程中报错,先临时移除该插件,再把集成逐个加回来,这样就能把"配置本身的问题"与"插件兼容性问题"区分开:

  1. 删除出问题的插件后重新 farm build,确认构建恢复;
  2. 逐个重新添加插件并重新构建,定位到具体是哪一个插件不兼容;
  3. 对该插件采取替代方案:换 Farm 官方插件、换 PostCSS 插件,或换框架特定集成;
  4. 结合浏览器控制台与终端日志,检查是否有 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