Farm CLI 全命令实战指南：start、build、watch、preview、clean 用法与底层原理

• 前端构建
• 构建工具
• 开发工具

Farm 是一个使用 Rust 编写的高性能 Vite 兼容 Web 构建工具，其官方 CLI（对应本仓库中的@farmfe/cli包）将编译能力封装为一组简洁的命令，覆盖开发、生产构建、监听重建、本地预览与缓存清理的完整工作流。本文以 Farm 1.x 版本的 CLI 文档 cli-api.md 为骨架，结合 packages/cli/src/index.ts 与 packages/core/src/index.ts 等源码实现，逐一讲解每条命令的用法、全部参数含义、参数与配置文件的映射关系，以及背后的执行原理，帮助你像熟悉 Vite CLI 一样熟练驾驭 Farm CLI。

一、CLI 概览：一条命令启动整个构建流程

Farm CLI 允许你在终端中直接完成应用的启动、构建、预览与监听四类核心操作。在项目目录下执行：

npx farm -h

即可看到完整的帮助信息（不同版本的输出略有差异，下文以 Farm 1.x 文档展示的farm/0.5.11输出为准）：

farm/0.5.11 Usage: $ farm [root] Commands: [root] Compile the project in dev mode and serve it with farm dev server build compile the project in production mode watch watch file change preview compile the project in watch mode clean [path] Clean up the cache built incrementally plugin [command] Commands for manage plugins For more info, run any command with the `--help` flag: $ farm --help $ farm build --help $ farm watch --help $ farm preview --help $ farm clean --help $ farm plugin --help Options: -l, --lazy lazyCompilation --host <host> specify host --port <port> specify port --open open browser on server start --hmr enable hot module replacement --cors enable cors --strictPort specified port is already in use, exit with error -c, --config <file> use specified config file -m, --mode <mode> set env mode --base <path> public base path --clearScreen allow/disable clear screen when logging -h, --help Display this message -v, --version Display version number

从源码实现看，CLI 使用cac命令解析库构建（见 packages/cli/src/index.ts），版本号由@farmfe/cli与@farmfe/core两部分拼接而成（见 packages/cli/src/index.ts）。每个命令都可通过--help查看自身专属参数，命令执行后由 packages/cli/src/utils.ts 中的resolveCore()动态加载@farmfe/core核心模块，再调用其导出的start、build、watch、preview、clean函数（见 packages/core/src/index.ts）。这种"CLI 负责解析参数、Core 负责实际编译"的分层设计，保证了 CLI 极轻量（仅依赖cac，见 packages/cli/package.json）。

二、全局选项：所有命令共享的参数基础

下列选项在所有命令中通用，由 CLI 在注册各命令前统一声明（见 packages/cli/src/index.ts）：

需要特别说明的是--config：在 packages/cli/src/utils.ts 中，getConfigPath()会将相对路径基于项目根目录解析为绝对路径。若你不指定配置文件，Farm 会按上文列出的默认文件名顺序自动探测。

三、start / dev：启动开发服务器

farm start（即无子命令直接运行farm [root]，源码中同时注册了dev别名，见 packages/cli/src/index.ts）用于在开发环境下编译代码并启动 Farm 开发服务器。完整参数如下：

Usage: $ farm [root] Options: -l, --lazy lazyCompilation --host <host> specify host --port <port> specify port --open open browser on server start --hmr enable hot module replacement --cors enable cors --strictPort specified port is already in use, exit with error -c, --config <file> use specified config file -m, --mode <mode> set env mode --base <path> public base path --clearScreen allow/disable clear screen when logging

参数逐个说明如下：

• -l, --lazy：开启lazy compilation（懒编译），默认true。开启后仅当模块被实际请求时才编译该模块及其依赖，极大加快大型项目的冷启动速度。它的实现位于 packages/core/src/server/middlewares/lazyCompilation.ts：浏览器请求以__lazy_compile为前缀的路径时，中间件解析paths参数并调用compiler.update()增量编译指定模块，然后以 JSON（Node 环境）或 ES 模块（浏览器环境）的形式返回动态资源映射。注意：lazyCompilation 仅在开发模式下生效，且与treeShaking互斥——若同时开启两者，源码会输出警告并将懒编译强制关闭（见 packages/core/src/config/normalize-config/index.ts）。
• --host <host>：指定服务器监听的主机名，例如--host 0.0.0.0允许局域网访问。
• --port <port>：指定端口号。
• --open：服务器启动后自动在浏览器中打开页面。
• --hmr：开启热模块替换（Hot Module Replacement），开发体验的核心功能。
• --cors：开启跨域资源共享（CORS）头。
• --strictPort：当指定端口已被占用时直接报错退出，而不是自动切换到下一个可用端口（默认true）。

从源码调用链看，该命令最终构造FarmCliOptions并调用start()（见 packages/cli/src/index.ts），而 packages/core/src/index.ts 中的start()会执行Server.createServer(inlineConfig)创建服务器、server.listen()启动监听，最后server.printUrls()打印访问地址。开发服务器的完整装配（HTTPS 配置、public 文件处理、中间件栈、HMR 引擎、WebSocket 服务器等）可参考 packages/core/src/server/index.ts。

实际使用示例：

# 以当前目录为根启动开发服务器（等价于 farm dev） farm # 指定端口与主机，并自动打开浏览器 farm start --port 3000 --host 0.0.0.0 --open # 关闭懒编译、开启 CORS farm dev --lazy=false --cors

四、build：生产构建

farm build将项目编译为可直接部署到生产环境的产物，默认输出到dist目录：

Usage: $ farm build Options: -o, --outDir <dir> output directory -i, --input <file> input file path -w, --watch watch file change --targetEnv <target> transpile targetEnv node, browser --format <format> transpile format esm, commonjs --sourcemap output source maps for build --treeShaking Eliminate useless code without side effects --minify code compression at build time -c, --config <file> use specified config file -m, --mode <mode> set env mode --base <path> public base path --clearScreen allow/disable clear screen when logging -h, --help Display this message

参数含义与约束如下：

• -o, --outDir <dir>：指定输出目录，映射为compilation.output.path。
• -i, --input <file>：指定入口文件路径，映射为compilation.input.index。
• -w, --watch：构建完成后进入监听模式。
• --targetEnv <target>：指定转译目标运行环境。根据 packages/cli/src/types.ts，可选值包括browser、node、node16、node-legacy、node-next、browser-legacy、browser-es2015、browser-es2017、browser-esnext、library。若不指定，Farm 会自动判断：当所有入口都是脚本文件（.js/.ts/.jsx/.tsx）时默认为library，否则默认为browser（见 packages/core/src/config/normalize-config/normalize-output.ts）。
• --format <format>：指定转译模块格式，可选esm或commonjs（即cjs）。
• --sourcemap：为构建产物生成 source map。
• --treeShaking：开启 Tree Shaking，剔除无副作用的无用代码。
• --minify：构建时压缩代码。

从调用链看，build命令组装compilation配置后调用 Core 的build()（见 packages/cli/src/index.ts）。build()内部先以'build'模式解析配置，再创建Compiler并进入_internalBuild()（见 packages/core/src/index.ts）：该函数会按顺序执行 JS 插件的configureCompiler钩子、编译整个模块图、输出"Build completed in ..."耗时日志，最后writeResourcesToDisk()将产物写入磁盘。生产模式下产物文件名默认会带上内容哈希：[resourceName].[contentHash].[ext]（见 packages/core/src/config/normalize-config/normalize-output.ts），有利于长缓存策略。

# 默认生产构建到 dist farm build # 指定输出目录、入口，开启 sourcemap 与压缩 farm build -o dist-prod -i src/main.ts --sourcemap --minify # 面向 Node 环境、输出 CommonJS 格式 farm build --targetEnv node --format commonjs

五、preview：本地预览生产产物

farm preview用于在本地预览生产构建产物。必须先执行farm build生成产物，再运行该命令：

Usage: $ farm preview Options: --open [url] Whether to open the page in the browser at startup --port <port> Set the port number for Server snooping --host <host> Specify the host to listen to when Server starts -c --config <config> Specify the profile path -h, --help Show command help

参数说明：

• --open [url]：启动时是否在浏览器打开页面，可选填具体 URL。
• --port <port>：设置预览服务器监听端口。
• --host <host>：指定预览服务器监听的主机。
• -c --config <config>：指定配置文件路径（CLI 源码中还额外支持--outDir指定产物目录，默认dist，见 packages/cli/src/index.ts）。

预览服务器在 Core 中由PreviewServer实现（见 packages/core/src/server/preview.ts）：它以'preview'模式解析配置，组装中间件栈——包括基于sirv的静态文件服务、@polka/compression压缩、CORS、代理等，最后监听端口并注册 SIGTERM 退出处理。也就是说，preview 与 dev 服务器共享了大量基础设施（HTTP 服务器、代理、CORS 等），区别在于前者只负责伺服已构建的静态产物，不再进行任何编译。

# 先构建，再预览 farm build farm preview --port 8080 --open

六、watch：监听文件变化并持续重建

farm watch一般用于node环境下的开发：监听文件变化，发生变化时自动重新构建：

Usage: $ farm watch Options: --format <format> transpile format esm, commonjs -o, --outDir <dir> output directory -i, --input <file> input file path -c, --config <file> use specified config file -m, --mode <mode> set env mode --base <path> public base path --clearScreen allow/disable clear screen when logging -h, --help Display this message

其工作流程（见 packages/core/src/index.ts）为：

1. 以'watch'模式解析配置并创建Compiler；
2. 若配置开启了lazyCompilation，则额外启动一个懒编译服务器（Server.createAndStartLazyCompilationServer），监听模块按需编译请求；
3. 执行一次完整构建；
4. 调用watchFileChangeAndRebuild()挂起监听，文件变动时递归调用自身触发重建。

底层文件监听基于chokidar实现（见 packages/core/src/watcher/index.ts），并通过Watcher事件总线对外暴露add、change、unlink等事件。适合 Electron 主进程、Node 服务端代码等"编译输出即可运行"的场景。

# 监听当前项目并持续输出到 dist farm watch -o dist -i src/index.ts --format commonjs

七、clean：清理增量构建缓存

farm clean用于清理 Farm 增量构建产生的本地缓存文件。由于 Farm 默认启用持久化缓存（persistent cache），当出现"不可预测的编译错误"或升级依赖后行为异常时，清缓存是最常见的排障手段：

Usage: $ farm clean [path] Options: --recursive Recursively search for node_modules directories and clean them -c, --config <file> use specified config file -m, --mode <mode> set env mode --base <path> public base path --clearScreen allow/disable clear screen when logging -h, --help Display this message

关键细节：

• 缓存位置：默认缓存目录为node_modules/.farm/cache（见 packages/core/src/config/normalize-config/normalize-persistent-cache.ts），可通过配置项compilation.persistentCache.cacheDir自定义，clean命令正是读取该配置拿到实际缓存路径。
• --recursive：递归查找node_modules目录并逐个清理其中的 Farm 缓存，适合 monorepo 场景。
• 清理行为：clean()会先统计目录，若目录存在则递归删除，并打印✨ ✨ Cache cleaned at ...；若目录不存在则提示No cached files found in ...（见 packages/core/src/index.ts）。

# 清理当前项目的 Farm 缓存 farm clean # 递归清理所有 node_modules 下的缓存（monorepo / 多包仓库） farm clean --recursive

八、源码视角：CLI 参数是如何映射到编译配置的

理解参数映射能让你在"命令行参数"与"farm.config.ts 配置"之间自由切换。以 packages/cli/src/index.ts 的实现为例，各命令的映射关系如下：

其中dev命令在组装选项时还会调用resolveCommandOptions()做两项预处理（见 packages/cli/src/utils.ts）：filterDuplicateOptions()在重复传参时取最后一个值；cleanOptions()剔除config、mode、base等全局选项，避免它们被误传给服务器配置。这解释了为什么全局选项与命令专属选项可以混用而不会互相干扰。

九、实战提示与常见问题排查

1. 端口被占用怎么办

farm start默认strictPort为true，端口被占用会直接报错退出；若希望自动寻找空闲端口，可在配置文件中设置server.strictPort: false。preview命令同样支持--strictPort（见 packages/cli/src/index.ts）。

2. 遇到"不可预测"的编译错误

优先执行farm clean清理node_modules/.farm/cache后重新构建——持久化缓存中的损坏项通常是此类问题的元凶。若项目在 CI 或 monorepo 中构建，可配合--recursive一次性清理所有子包的缓存。

3. 构建体积没有降下来

确认--treeShaking与--minify均已开启，并注意 lazyCompilation 模式不支持 treeShaking（二者同时启用时懒编译会被自动关闭并输出警告，见 packages/core/src/config/normalize-config/index.ts）。

4. 需要监听 Node 端代码

使用farm watch --targetEnv node --format commonjs，Farm 会按需编译并在文件变化后重建；若同时开启懒编译，还会启动一个懒编译服务器以加速 Node 侧动态 import 场景（参考 packages/core/src/server/middlewares/lazyCompilation.ts）。

5. 快速确认可用命令

随时执行farm --help、farm build --help查看各命令当前版本的完整参数列表；版本号可通过farm -v查看，输出包含 CLI 与 Core 两部分版本，便于排查升级问题。

总结

Farm CLI 用五个命令覆盖了开发到部署的完整链路：farm（或farm dev）驱动开发服务器并内置懒编译与 HMR，farm build产出带内容哈希的生产产物，farm preview伺服构建结果，farm watch面向 Node 环境的持续重建，farm clean兜底处理增量缓存问题。其参数与farm.config.ts的配置字段一一对应，本文给出的映射表可作为你切换命令行与配置文件两种配置方式的速查手册。更多配置项细节可参考仓库中的 CLI 实现（packages/cli/src/index.ts）与配置解析源码（packages/core/src/config）。

• 前端构建
• 构建工具
• 开发工具