Farm CLI 命令行参考：create、start、build、preview、watch 全流程实操与源码解析

前端构建构建工具开发工具【免费下载链接】farmExtremely fast Vite-compatible web build tool written in Rust项目地址https://gitcode.com/gh_mirrors/fa/farm点击查看免费下载Farm 的命令行入口由farmfe/cli提供覆盖从脚手架创建项目create farm、启动开发服务器farm start、生产构建farm build到产物预览farm preview和库模式监听编译farm watch的完整工作流。本文以仓库中的 CLI 文档为骨架结合packages/cli的命令定义源码与farmfe/core的入口实现逐命令说明每个子命令的行为、可用参数、默认值以及参数在源码中如何被解析并传入编译器帮助你既能照着敲命令也能看懂命令背后的调用链。安装与环境要求farm命令由 npm 包farmfe/cli提供其 package.json 声明了以下关键事实二进制入口为bin字段注册的./bin/farm.mjs即安装后全局可用farm命令运行环境要求node 16唯一运行时依赖是 cacFarm 用它解析命令行参数当前仓库内版本为2.0.0-beta.0。典型安装方式见 packages/cli/README.mdpnpm add farmfe/cli -D启动脚本--debug 的隐藏行为在真正执行 CLI 逻辑前入口脚本 farm.mjs 还有一段值得注意的前置处理#!/usr/bin/env node if (process.argv.includes(--debug)) { process.env.DEBUG farm:*; } import(../dist/index.js)也就是说任意farm命令带上--debug都会自动把环境变量DEBUG设为farm:*从而打开 Farm 内部的 debug 日志通道。这与 CLI 源码中声明的-d, --debug [feat]全局选项见下文配合使用。create创建一个新的 Farm 项目Farm 提供独立的脚手架包create-farm不占用farm主命令的子命令位。任意你喜欢的包管理器都可以使用pnpm create farm # or npm create farm # or yarn create farm从源码看create-farm 包 是一个基于 N-API 构建的 Rust 工具package.json中napi.binaryName为create-farm并预编译了x86_64-unknown-linux-gnu、aarch64-apple-darwin、x86_64-pc-windows-msvc等多平台二进制。其 Node 侧入口最终调用 Rust 函数实现在 crates/create-farm-rs 中而项目模板文件含 React、Vue、Preact 等多种模板的package.json、tsconfig、样式文件就存放在 crates/create-farm-rs/templates 目录下供交互式选择生成。start启动开发服务器farm start启动开发服务器以开发模式编译项目并监听文件变化。注意在源码中这其实是“默认命令”CLI 主入口 定义了命令[root]描述为 “Compile the project in dev mode and serve it with farm dev server”并注册了start和dev两个别名。因此以下三种写法完全等价farm # 默认命令 farm start # 别名 farm dev # 别名start 的命令行参数参数定义集中在 packages/cli/src/index.ts逐项说明如下选项说明默认值-l, --lazy开启 lazy compilation按需编译只编译当前页面实际用到的模块描述标注为true--host host指定服务器监听的主机名见下方“默认值”--port port指定端口开发服务器默认9000--open服务器启动后自动打开浏览器默认关闭--hmr开启热模块替换HMR由配置决定--cors开启 CORS默认关闭--strictPort指定端口已被占用时直接报错退出描述标注为true--target target指定输出目标环境如node、browser—--format format指定输出格式esm或commonjs—--sourcemap输出 source map—--treeShaking消除无副作用的死代码—--minify构建时压缩代码—关于默认端口与主机名core 的默认服务器配置 给出了具体数值开发服务器port默认9000可用环境变量FARM_DEFAULT_SERVER_PORT覆盖host默认localhostopen、strictPort、cors默认均为falsepreview 服务器的port默认为1911distDir默认为dist。start 的参数如何进入编译器start命令的 action 回调index.ts会把 CLI 参数组装成FarmCliOptions对象再调用 core 导出的start函数const defaultOptions: FarmCliOptions { root, server: resolveOptions, clearScreen: options.clearScreen, configFile: options.config, mode: options.mode, compilation: { lazyCompilation: options.lazy, output: { path: options?.outDir, targetEnv: options?.target, format: options?.format }, input: { index: options?.input }, sourcemap: options.sourcemap, minify: options.minify, treeShaking: options.treeShaking } };这里能看到一条清晰的映射关系--lazy→compilation.lazyCompilation--target→compilation.output.targetEnv--format→compilation.output.format--sourcemap/--minify/--treeShaking→compilation下的同名布尔项。一个细节是--base path全局选项的处理在 action 内它被单独转换成compilation.output.publicPathindex.ts即 CLI 层面的--base最终落到配置层面的publicPath上。core 侧的入口 start 函数 则负责创建并监听服务器export async function start( inlineConfig?: FarmCliOptions UserConfig ): Promisevoid { try { const server await Server.createServer(inlineConfig); await server.listen(); server.printUrls(); } catch (error: any) { new Logger().error(Failed to start the server, { exit: false, error }); } }CLI 传入的 inlineConfig 与farm.config.*文件中的配置会在 core 的配置解析阶段合并CLI 参数优先级更高因此你可以用命令行临时覆盖配置文件中的服务器与编译选项。build生产模式构建farm build以生产模式编译项目。命令定义见 index.ts同样支持位置参数root指定项目根目录farm build ./my-projectbuild 的命令行参数选项说明-o, --outDir dir输出目录配置层默认./dist见 DEFAULT_COMPILATION_OPTIONS-i, --input file指定入口文件--target target输出目标环境node、browser、library--format format输出格式esm、commonjs--sourcemap输出 source map--treeShaking启用 tree shaking--minify启用代码压缩关于--target的完整取值范围CLI 的类型定义 比命令行帮助文本更细除browser、node、library外还包含node16、node-legacy、node-next、browser-legacy、browser-es2015、browser-es2017、browser-esnext等细分档位适合需要精确控制产物语法级别的库项目。build 的底层调用链core 的 build 函数 揭示了 build 的内部流程export async function build( inlineConfig: FarmCliOptions UserConfig {} ): Promisevoid { const resolvedUserConfig await resolveConfig( inlineConfig, build, production ); const compiler createCompiler(resolvedUserConfig); await _internalBuild(compiler, resolvedUserConfig); }可以推断出三步走resolveConfig(inlineConfig, build, production)把 CLI 内联配置与配置文件按 “build / production” 环境合并成最终配置createCompiler基于配置创建 Rust 侧编译器实例随后_internalBuild执行真正的工作index.ts依次触发 JS 插件的configureCompiler钩子、按需清理输出目录output.clean、调用compiler.compile()完成后通过compiler.writeResourcesToDisk()把产物写入磁盘并打印Build completed in ... Resources emitted to ...耗时信息。若配置了persistentCache完成信息中还会附带持久化缓存的品牌标识。一个实用的仓库实例是 SSR 场景下用--config指定多份配置构建见 website/docs/advanced/ssr.md 中的 scripts 片段{ build: farm build, build:server: farm build --config farm.config.server.mjs }preview预览 build 产物farm build farm previewpreview用于本地起一个静态服务器预览build命令生成的产物避免为了看一眼效果而重新走一遍完整构建。命令定义见 index.ts参数如下选项说明--host [host]指定主机名--port port指定端口默认1911--open启动预览服务器时自动打开浏览器--outDir dir要服务的产物目录默认dist--strictPort端口被占用时退出从 action 回调index.ts可以看到这些参数会被打包成server.preview配置host、port、open、strictPort、distDir同时outDir也会同步写入compilation.output.path若带了--base同样会被改写为publicPath。core 侧的 preview 函数 创建一个PreviewServer实例并调用createPreviewServer()与listen()出错时打印 “Failed to start the preview server”。也就是说preview本质是一个只服务已构建静态资源的轻量服务器与start的完整开发服务器含按需编译、HMR 能力是两条不同的代码路径。watch库项目的监听编译farm watch官方文档对watch的定位是通常用于编译库library项目。它的行为类似start的监听编译模式但不会启动面向浏览器的开发服务器而是把产物真实地写出到磁盘并在文件变化时增量重建。watch 的命令行参数命令定义见 index.ts选项说明-o, --outDir dir输出目录-i, --input file入口文件--target target输出目标环境node、browser、library--format format输出格式esm、commonjs--sourcemap输出 source map值得注意watch的参数集比build少了--treeShaking和--minify从源码看watch 命令的 action 只透传了outDir、input、target、format、sourcemap这几项编译选项index.ts因此压缩与 tree shaking 这类生产优化项需要通过farm.config.*配置文件来控制。watch 的底层行为core 的 watch 函数 展示了它和build的异同export async function watch( inlineConfig: FarmCliOptions UserConfig {} ): Promisevoid { const resolvedUserConfig await resolveConfig(inlineConfig, watch); const compiler createCompiler(resolvedUserConfig); if (resolvedUserConfig.compilation?.lazyCompilation) { const server await Server.createAndStartLazyCompilationServer(resolvedUserConfig); server.compiler compiler; } await _internalBuild(compiler, resolvedUserConfig); await watchFileChangeAndRebuild(resolvedUserConfig, compiler, () watch(inlineConfig) ); }从源码结构看watch 做了三件事先按watch环境解析配置注意它没有像build那样显式指定production若开启了lazyCompilation会额外启动一个懒编译服务器来支撑按需编译然后执行首次_internalBuild最后由watchFileChangeAndRebuild进入文件监听循环变更时触发增量重建。仓库中的 examples/lib-watch 示例即是一个典型的 watch 场景多入口的库项目配合 farm.config.mjs 进行持续编译仓库文档中也出现了farm watch --config farm.config.server.mjs这样的多配置用法website/docs/advanced/ssr.md。全局选项与 clean 命令所有命令共享的全局选项在 CLI 主入口 中以下选项注册在命令层对start/build/watch/preview均生效选项说明-c, --config file使用指定配置文件缺省时按farm.config.js / farm.config.ts / farm.config.mjs / farm.config.cjs / farm.config.mts / farm.config.cts顺序查找-m, --mode mode设置 env 模式--base path设置 public base path映射到output.publicPath-d, --debug [feat]显示 debug 日志可带特性名--clearScreen控制日志时是否清屏默认true-h, --help显示帮助-v, --version显示版本几个实现细节配置文件查找顺序。core 侧的 DEFAULT_CONFIG_NAMES 定义了实际查找顺序farm.config.ts→farm.config.js→farm.config.cjs→farm.config.mjs→farm.config.cts→farm.config.mts由 loadConfigFile 依次 stat 确认存在。若用--config显式指定则直接path.resolve(root, configFile)解析绝对路径。配置加载失败的排错提示。当配置文件解析失败时load-config-file.ts 会抛出带“Potential solutions”的错误提示可尝试设置FARM_CONFIG_FORMATcjs默认 esm或FARM_CONFIG_FULL_BUNDLE1对使用 TS 或特殊模块格式的配置文件很有用。重复参数去重。CLI 的 utils.ts 中filterDuplicateOptions会在同一选项出现多次时只取最后一个值并在cleanOptions中剥离-/m/c等短选项键保证传给 core 的 options 是干净的。版本信息。-v, --version会同时打印farmfe/cli与farmfe/core两个包的版本index.tscore 版本来自动态导入farmfe/core时拿到的VERSION常量便于核对 CLI 与 core 是否匹配。懒加载 core。CLI 通过 resolveCore 用await import(farmfe/core)动态加载核心包如果加载失败会以 “Cannot find farmfe/core module, Did you successfully install” 的提示直接退出。这意味着farmfe/cli本身很轻重量级能力全部在farmfe/core。clean清理持久化缓存源码中有、文档未单列的命令除官方 CLI 文档列出的四个命令外源码中还定义了第五个子命令cleanindex.ts用于清理 Farm 的持久化增量缓存farm clean [path]选项说明--recursive递归查找node_modules目录并清理其下的缓存其实现 clean 函数 会先以 “build / production” 环境解析出配置取出compilation.persistentCache.cacheDir作为要清理的路径若不存在则打印 “No cached files found” 警告成功删除后打印 “Cache cleaned at ...”。当持久化缓存导致产物异常时这是一个标准的排查手段。参数传递的整体机制小结把上面的源码证据串起来Farm CLI 的完整数据流是bin/farm.mjs 处理--debug后加载编译产物cac 实例 解析命令、别名与选项参数类型约束见 types.ts各命令 action 将 CLI 参数组装为FarmCliOptions类型定义见 config/types.ts其中server、compilation、configFile、mode、root等字段分别对应开发服务器、编译行为、配置文件与环境模式core 的start/build/watch/preview入口packages/core/src/index.ts调用resolveConfig合并配置文件与 CLI 内联配置再由 Rust 侧 Compiler 完成实际编译与产物输出。这一分层设计也解释了 CLI 参数的优先级语义命令行选项总是以内联配置形式进入resolveConfig因此可以临时覆盖farm.config.*中的同名配置适合 CI 或一次性实验性构建而不必改动项目配置文件。适用前提与限制命令行为以当前仓库farmfe/cli2.0.0-beta.0Node 16为准beta 阶段个别参数默认值可能与正式发布版有差异farm命令需在安装过farmfe/cli的项目中运行核心能力依赖farmfe/core的动态加载部分参数如--lazy默认开启 lazy compilation、开发/预览服务器默认端口 9000/1911均以本仓库 constants.ts 中的默认值为准可通过FARM_DEFAULT_SERVER_PORT等环境变量覆盖更完整的命令与参数表格可参考仓库文档 website/docs/cli/cli-api.md其与本文所述的源码定义保持一致。赞分享前端构建构建工具开发工具【免费下载链接】farmExtremely fast Vite-compatible web build tool written in Rust项目地址https://gitcode.com/gh_mirrors/fa/farm点击查看免费下载相关推荐Farm CLI 命令与选项全解farm dev、build、watch、preview、clean 的参数详解与源码实现Farm CLI 命令与选项全解farm dev、build、watch、preview、clean 的参数详解与源码实现 本文基于 Farm 仓库的 CLI前端构建构建工具开发工具VitePress 命令行接口CLI完整参考dev / build / preview / init 命令实战指南VitePress 命令行接口CLI完整参考dev / build / preview / init 命令实战指南 本篇指南基于 VitePress 官方前端文档VitePress CLI 命令行完全指南dev、build、preview 与 init 命令详解VitePress CLI 命令行完全指南dev、build、preview 与 init 命令详解 VitePress 是一套基于 Vite 与 Vue 的前端文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考