VuePress 命令行接口（CLI）完全指南：dev、build、eject 与自定义命令实战
VuePress 命令行接口（CLI）完全指南：dev、build、eject 与自定义命令实战
本文档系统讲解 VuePress 的命令行接口（CLI），覆盖 vuepress <command> targetDir <a href="https://link.gitcode.com/i/0ed155f6d78b9869299046d2ca4adecc" target="_blank">options] 的基本用法、dev/build/eject 三大内置命令的全部选项及默认值，并结合 [packages/vuepress 包的源码实现，深入剖析选项如何被解析、传递给核心逻辑，以及如何通过插件 extendCli 注册自定义命令。读完本文，你将能熟练运用 CLI 完成文档站点的开发、构建、主题弹出与命令扩展。
基本用法
VuePress 的命令行入口由 packages/vuepress/cli.js 提供（其 bin 字段将 vuepress 命令映射到该文件），统一语法为：
vuepress <command> targetDir [options]
<command>：要执行的命令，内置命令包括dev、build、eject，外加用于环境诊断的info；targetDir：文档站点源码目录（即包含.vuepress目录的目录），可选，省略时默认使用当前工作目录.；[options]：各命令专属的命令行选项，见下文。
从 packages/vuepress/lib/registerCoreCommands.js 的源码可以看到，dev 与 build 的 action 中都执行了 path.resolve(sourceDir)，将传入的 targetDir 解析为绝对路径后作为 sourceDir 传给核心逻辑；若省略该参数，则直接以当前目录 . 作为源码目录。
命令行解析本身基于 CAC 中的 CLI() 函数负责创建 CAC 实例、执行 beforeParse/afterParse 钩子并解析 process.argv。启动时还会通过 packages/vuepress/lib/checkEnv.js 校验 Node 版本是否满足 @vuepress/core 的 engines.node 要求（本仓库要求 >=8.6），不满足则直接退出并提示升级。
build：生成静态站点
build 命令用于在指定目录生成静态站点：
vuepress build targetDir [options]
该命令由 packages/vuepress/lib/registerCoreCommands.js 注册，实际调用 @vuepress/core 的 build 函数完成站点编译与静态化输出。
-p, --port <port>
指定开发服务器端口，详见 配置文档 port。
- 类型：
number - 默认值：
8080 - 说明：该选项在
build与dev命令上均可用；源码中标注的默认提示为(default: 8080)。
-t, --temp <temp>
设置客户端临时文件目录，详见 配置文档 temp。
- 类型：
string - 默认值：
/path/to/@vuepress/core/.temp - 说明：VuePress 在构建过程中会生成大量临时文件（如路由、站点数据、页面组件等，见 internal-plugins），该选项允许你将其重定向到自定义路径。
-c, --cache [cache] 与 --no-cache
缓存相关选项，详见 配置文档 cache：
vuepress dev docs --cache .cache # 设置缓存路径
vuepress dev docs --no-cache # 每次构建前清除缓存
- 类型：
boolean | string - 默认值：
true - 说明：VuePress 默认借助 cache-loader 大幅加速 webpack 编译。
--cache <path>指定缓存目录，--no-cache则会在每次构建前移除缓存。注意源码中该选项的定义为-c, --cache [cache]，方括号表示值可选。
--dest <dest>
指定构建输出目录，详见 配置文档 dest：
- 类型：
string - 默认值：
.vuepress/dist - 说明：若指定相对路径，将基于
process.cwd()解析。源码中同时保留了-d, --dest <dest>与--dest <dest>两种写法以兼容不同调用习惯。
--debug
以调试模式启动开发服务器（或进行构建）。对应源码中 logger.setOptions({ logLevel: silent ? 1 : debug ? 4 : 3 }) 与 env.setOptions({ isDebug: debug, ... }) 的逻辑（registerCoreCommands.js）：开启 --debug 后日志级别提升至 4（更详细），并写入 env.isDebug 供运行时判断。
--silent
以安静模式启动，将日志级别降至 1，只输出关键信息，适合 CI 等场景。
--max-concurrency
设置渲染文档的最大并发量：
vuepress build docs --max-concurrency 4
该选项用于控制构建静态站点时同时处理的文档数量。当站点包含大量文档、构建过程可能造成内存溢出时，建议通过调小该值来限制并发、降低内存峰值。
其他可用的 build 选项
build 同样支持 --host <host>、--open、--no-clear-screen（完整定义见 registerCoreCommands.js），这些选项主要服务于构建过程的开发服务器相关行为。
dev：启动开发服务器
dev 命令启动带热更新的开发服务器：
vuepress dev targetDir [options]
来自 vuepress build 的所有选项（--port、--temp、--cache、--no-cache、--debug、--silent 等）在 dev 下均可用。除此之外，dev 还有几个专属选项：
--host <host>
指定开发服务器监听的主机，详见 配置文档 host。
- 类型：
string - 默认值：
'0.0.0.0' - 说明：默认监听所有网卡地址，便于局域网内访问；如需仅本机访问，可设为
127.0.0.1或localhost。
--open
当服务端准备就绪时自动打开浏览器。适合本地开发时省去手动输入地址的步骤。
--no-clear-screen
当 dev server 就绪时不清除屏幕，方便保留终端中的历史输出。请注意：dev server 在调试模式下不会清除屏幕，这是源码中约定的行为。
eject：弹出默认主题
vuepress eject targetDir
eject 命令会将默认主题完整复制到 .vuepress/theme 目录，供你在此基础上自定义（registerCoreCommands.js）。执行后，你可以直接修改弹出的主题源码，实现深度定制而不必维护整套主题。该命令同样支持 --debug 选项。
弹出后的主题源码结构可参考仓库内的 packages/@vuepress/theme-default，其 layouts/、components/、styles/ 等目录即是被复制的主体内容。
info：查看本地环境信息
除文档列出的三个命令外，CLI 还内置了 info 命令（registerCoreCommands.js）：
vuepress info
它会调用 envinfo 输出当前系统的 OS/CPU、Node/Yarn/npm 版本、常用浏览器版本，以及 vuepress、@vuepress/core、@vuepress/theme-default 等包的安装情况，是排查环境问题时非常实用的诊断工具。
自定义命令：extendCli
除内置命令外，你可以通过插件选项 extendCli 注册自定义命令，详见插件选项 API 文档。
- 类型：
function - 默认值：
undefined - 说明：该函数会接收到一个 CAC 实例作为第一个参数，你可以在其中调用
.command()/.option()/.action()链式注册新命令。
示例（来自 option-api.md）：
module.exports = {
extendCli (cli) {
cli
.command('info [targetDir]', '')
.option('--debug', 'display info in debug mode')
.action((dir = '.') => {
console.log('Display info of your website')
})
}
}
注册后即可在项目中使用 vuepress info [targetDir]。
自定义命令的定位机制
自定义命令能否正常工作，依赖 VuePress 对站点配置的自动定位。packages/vuepress/lib/handleUnknownCommand.js 中通过 inferUserDocsDirectory(cwd) 用 globby 递归查找 **/.vuepress/config.(js|ts)（排除 node_modules），从而推断出用户文档目录；随后调用 app.pluginAPI.applySyncOption('extendCli', cli, app) 在完整上下文中注册插件命令（handleUnknownCommand.js）。
因此官方文档特别提示：插件注册的自定义命令要求 VuePress 能像 vuepress dev、vuepress build 一样定位到你的站点配置。开发命令时，务必引导用户把 targetDir 作为 CLI 参数传入，否则可能触发 "Unknown command" 并提示 Did you miss to specify the target docs dir? 的报错信息。
源码视角：CLI 的启动与错误处理
理解 CLI 的底层机制有助于排查问题，关键源码路径如下：
-
入口与版本检查：packages/vuepress/cli.js 启动时依次执行
checkEnv(pkg)（Node 版本校验）、updateNotifier（版本更新提醒）、registerCoreCommands(cli, OPTIONS)（注册内置命令）、handleUnknownCommand(cli, OPTIONS)（注册自定义命令兜底），最后调用cli.version(pkg.version).help()注册--version/--help。若用户未传任何参数，afterParse会直接输出帮助信息。 -
命令分发：packages/vuepress/lib/util.js 中的
isKnownCommand(argv)判断首个参数是否为dev/build/eject/info之一，内置命令走正常分发，其余命令进入自定义命令处理流程。 -
错误兜底：util.js 中的
wrapCommand(fn)包装所有命令的 action，若执行过程中抛出异常，会以红色输出错误堆栈并将进程退出码置为1，避免静默失败。 -
日志与调试开关：
--debug、--silent通过logger.setOptions控制日志级别（silent=1、默认=3、debug=4），--debug还会设置env.isDebug（registerCoreCommands.js），进而影响核心模块的调试行为。
常用命令速查
| 命令 | 作用 | 常用选项 |
|---|---|---|
vuepress dev [targetDir] |
启动带热更新的开发服务器 | --port、--host、--open、--no-cache、--debug、--no-clear-screen |
vuepress build [targetDir] |
构建静态站点 | --dest、--temp、--cache、--no-cache、--max-concurrency、--silent |
vuepress eject [targetDir] |
将默认主题复制到 .vuepress/theme |
--debug |
vuepress info |
输出本地环境诊断信息 | 无 |
vuepress <自定义命令> |
执行插件通过 extendCli 注册的命令 |
由插件定义 |
结合本文的选项说明与配置文档中的类型、默认值定义，你可以针对不同项目场景（本地开发、CI 构建、大型文档站点内存调优）灵活组合命令行参数，充分发挥 VuePress CLI 的完整能力。