VitePress 命令行接口CLI完整指南dev、build、preview 与 init 实战详解【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepress导读本文是 VitePress 命令行接口Command Line Interface的完整参考覆盖vitepress dev、vitepress build、vitepress preview与vitepress init四个核心命令的用法、全部参数及其底层实现原理。读完本文你将掌握如何用一条命令启动开发服务器、构建生产站点、本地预览产物以及通过交互式向导快速初始化一个文档项目并理解每个参数在源码中的真实作用与影响范围。vitepress dev启动开发服务器vitepress dev以指定目录作为站点根目录启动 VitePress 开发服务器默认使用当前目录。在开发阶段它会利用 Vite 的开发服务器能力提供模块热更新HMR、Markdown 实时编译等体验。用法# 在当前目录启动可省略 dev 子命令 vitepress # 在子目录如 ./docs中启动 vitepress dev [root]值得注意的是当不带子命令直接运行vitepress时CLI 会默认进入 dev 模式。从 cli.ts 的源码可以看到命令解析逻辑为const command argv._[0]当command为空或等于dev时统一走 dev 分支root参数则取自argv._[command ? 1 : 0]并会被写入argv.root供后续配置解析使用。选项Option说明--open [path]启动时自动打开浏览器boolean \| string--port port指定端口number--base path公共基础路径默认/string--cors启用 CORS--strictPort若指定端口已被占用则直接退出boolean--force强制优化器忽略缓存并重新打包依赖boolean参数背后的源码行为这些参数并非凭空生效而是被直接透传或转换为 Vite 的配置--base在 server.ts 中createServer会取出serverOptions.base若为字符串则调用normalizeSiteBase(base)后覆盖config.site.base再作为base传入 Vite 的createViteServer。--force在 cli.ts 中做了特殊处理——若传入--forceCLI 会将其删除并改写为argv.optimizeDeps { force: true }从而让 Vite 依赖优化器忽略缓存强制重新预构建。--port、--strictPort、--cors等会随serverOptions一并传入 Vite 的server配置项由 Vite 原生处理。布尔值参数如--cors会经过一个字符串到布尔值的归一化转换true/false字符串被转为真正的布尔值确保 minimist 解析出的结果符合预期。dev 服务器启动后会打印 VitePress 与底层 Vite 的版本信息见 logVersion.ts并输出可访问的 URL。开发服务器快捷键dev 服务器运行期间支持一组键盘快捷键实现在 shortcuts.ts 中按下h可随时查看帮助列表按键作用r重启开发服务器u再次打印服务器 URLo在浏览器中打开站点c清空控制台q退出开发服务器快捷键仅在终端为 TTY 且非 CI 环境时生效按CtrlC或CtrlD也会关闭服务器并退出进程。重启时CLI 会依次执行配置重新解析、释放 markdown-it 实例disposeMdItInstance、清除 markdown→Vue 转换缓存clearCache、关闭旧服务器并重新拉起新服务器从而保证配置改动后完全生效。vitepress build构建生产站点vitepress build用于将站点构建为可部署的生产版本输出静态 HTML 与资源文件到outDir。用法vitepress build [root]从 build.ts 的源码看build 流程会先后执行两阶段任务先building client server bundles客户端与 SSR 服务端打包再rendering pages渲染页面并可选地在配置了sitemap.hostname时生成 sitemap最后调用buildEnd钩子并清理临时目录输出build complete in xx.xxs.的耗时统计。构建期间还会临时把项目内的vue软链接到 VitePress 自带的 Vue除非用户已自行安装构建完成后自动解除链接。选项Option说明--mpa实验性以 MPA 模式 构建不进行客户端水合boolean--base path公共基础路径默认/string--assetsBase url生成资源所服务的基础 URL 前缀例如 CDN 地址string--target target转译目标默认modulesstring--outDir dir输出目录相对cwd默认root/.vitepress/diststring--assetsInlineLimit number静态资源 base64 内联阈值单位字节默认4096number参数在源码中的落点--mpa在 build.ts 中传入--mpa会直接置siteConfig.mpa true。MPA 模式Multi-Page Application下每个页面独立加载、不进行客户端水合适合对 SEO 与页面体积有极致要求的场景但会失去 SPA 式的页面内切换体验。该模式在 siteConfig.ts 中被标记为实验性experimental。--base需要携带值例如--base /docs/若未携带值会抛出--base requires a value (e.g. --base /docs/)错误。该值经normalizeSiteBase归一化后覆盖siteConfig.site.base。--assetsBase同样必须有值例如--assetsBase https://cdn.example.com/经normalizeAssetsBase处理后写入siteConfig.assetsBase可用于把静态资源托管到 CDN。assetsBasePlugin.ts 会基于此改写资源 URL并支持与experimental.renderBuiltUrl钩子配合做更精细的 URL 重写。--outDir注意其基准是cwd当前工作目录而非 root——源码中使用path.resolve(process.cwd(), buildOptions.outDir)解析而配置文件中outDir相对 root 解析。两者基准不同使用命令行参数时务必留意。--assetsInlineLimit与--target作为 Vite/Rolldown 的构建选项向下传递控制资源内联阈值默认 4096 字节小于等于该体积的资源会被内联为 base64与代码转译目标。vitepress preview本地预览生产构建vitepress preview在本地启动一个静态服务器用于预览vitepress build的构建产物。用法vitepress preview [root]其实现位于 serve.ts底层使用polkasirv默认监听端口为4173而非 dev 服务器常用的端口。服务会启用 gzip 压缩与 ETag 缓存静态资源位于assetsDir内、带指纹的文件设置maxAge31536000且immutable非资源 HTML 页面则强制cache-control: no-cache要求浏览器每次回源校验。选项Option说明--base path公共基础路径默认/string--assetsBase url生成资源所服务的基础 URL 前缀例如 CDN 地址string--port port指定端口number预览服务的行为细节相对 base 处理如果--base是相对路径如./预览服务会将其视为可在任意挂载点工作直接以/提供服务若是外部绝对 URL则取其 pathname 部分作为 base。404 处理请求未命中时若请求的是非资源路径会返回构建产物中的404.html这正是--mpa/静态托管场景下自定义 404 页面的来源否则返回空白 404。--assetsBase的两种情形若为外部 URLCDN预览服务会提示资源将从该 URL 请求而非本地若为本地路径前缀则会在该前缀下镜像一份资源子树方便本地验证。CLI 别名在 cli.ts 中serve与preview是等价的command serve || command preview走同一分支因此vitepress serve与vitepress preview行为一致。vitepress init交互式初始化向导vitepress init在当前目录启动 Setup Wizard以交互问答方式帮你快速搭好一个可直接运行的 VitePress 项目骨架。用法vitepress init也可以按包管理器执行npx vitepress init、pnpm vitepress init、yarn vitepress init或bun vitepress init参见 getting-started.md。向导会依次询问的问题实现位于 init.ts基于clack/prompts默认值与选项如下问题默认值 / 可选值说明在何处初始化 VitePress 配置./站点根目录从何处寻找 Markdown 文件同 root即srcDir站点标题My Awesome Project写入站点配置站点描述A VitePress Site写入站点配置主题默认主题 / 默认主题自定义 / 自定义主题三种脚手架深度是否用 TypeScript 编写配置与主题是/否决定生成.ts还是.js/.mjs是否向 package.json 注入 VitePress npm scripts是/否注入dev/build/preview脚本是否给 npm scripts 加前缀是/否如docs:dev脚本前缀名docs例如生成docs:dev向导会生成什么根据所选主题类型脚手架会写入不同文件集合默认主题index.md、api-examples.md、markdown-examples.md、.vitepress/config.js当前仓库 template 目录即这些模板的源默认主题 自定义额外生成.vitepress/theme/index.js与.vitepress/theme/style.css自定义主题额外再生成.vitepress/theme/Layout.vue。此外脚手架会智能处理若项目package.json非 ESM无type: module配置文件会生成.mjs扩展名若选择 TypeScript 则转为.ts/.mts。若选择了自定义主题但项目未安装vue向导会在结束时提示显式安装vue作为开发依赖若目录是 git 仓库还会提醒把.vitepress/dist与.vitepress/cache加入.gitignore。若选择注入 npm scripts则默认生成以docs前缀为例{ scripts: { docs:dev: vitepress dev docs, docs:build: vitepress build docs, docs:preview: vitepress preview docs } }完成后按提示运行pnpm run docs:dev或对应的包管理器命令即可开始写作。参数解析与命令分发的统一机制所有 CLI 参数统一由 cli.ts 顶部的minimist(process.argv.slice(2))解析随后经过一个关键归一化步骤所有值为字符串true或false的参数都会被转换为真正的布尔值避免--cors、--strictPort这类开关被当作字符串传入。命令分发逻辑如下dev或省略命令走开发服务器分支支持--force改写为optimizeDeps.force并绑定快捷键与重启逻辑init进入初始化向导init.tsbuild调用build(root, argv)执行生产构建serve/preview调用serve(argv)启动预览服务器serve.ts其他未知命令直接报错unknown command xxx并以退出码 1 结束。无论是配置解析失败、dev 启动失败、build 出错还是预览启动失败都会走logErrorAndExit统一打印错误含错误栈并process.exit(1)便于 CI 等自动化场景捕获失败状态。常见实战组合以下组合覆盖了日常高频场景# 1. 初始化文档项目 npx vitepress init # 2. 在 docs 目录启动开发服务器固定端口并自动打开浏览器 vitepress dev docs --port 5174 --open # 3. 使用自定义 base 路径构建部署到子路径 /guide/ vitepress build docs --base /guide/ # 4. 资源托管 CDN 的构建 vitepress build docs --assetsBase https://cdn.example.com/assets/ # 5. 指定输出目录相对当前工作目录 vitepress build docs --outDir ./dist # 6. MPA 模式构建实验性 vitepress build docs --mpa # 7. 本地预览构建产物指定端口 vitepress preview docs --port 8080总结VitePress 的 CLI 将「开发—构建—预览—初始化」四个阶段收敛为四个简洁命令dev提供带 HMR 与快捷键的开发体验build产出可部署的静态站点并支持--base、--assetsBase、--mpa、--outDir、--assetsInlineLimit等生产级选项preview基于构建产物做本地验证默认 4173 端口init则通过交互向导一站式完成项目脚手架搭建。理解这些命令与参数在源码中的落点cli.ts、server.ts、build.ts、serve.ts、init.ts将帮助你在实际项目中更精准地配置构建与部署流程。【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 VitePress 命令行接口（CLI）完整指南：dev、build、preview 与 init 实战详解
VitePress 命令行接口CLI完整指南dev、build、preview 与 init 实战详解【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepress导读本文是 VitePress 命令行接口Command Line Interface的完整参考覆盖vitepress dev、vitepress build、vitepress preview与vitepress init四个核心命令的用法、全部参数及其底层实现原理。读完本文你将掌握如何用一条命令启动开发服务器、构建生产站点、本地预览产物以及通过交互式向导快速初始化一个文档项目并理解每个参数在源码中的真实作用与影响范围。vitepress dev启动开发服务器vitepress dev以指定目录作为站点根目录启动 VitePress 开发服务器默认使用当前目录。在开发阶段它会利用 Vite 的开发服务器能力提供模块热更新HMR、Markdown 实时编译等体验。用法# 在当前目录启动可省略 dev 子命令 vitepress # 在子目录如 ./docs中启动 vitepress dev [root]值得注意的是当不带子命令直接运行vitepress时CLI 会默认进入 dev 模式。从 cli.ts 的源码可以看到命令解析逻辑为const command argv._[0]当command为空或等于dev时统一走 dev 分支root参数则取自argv._[command ? 1 : 0]并会被写入argv.root供后续配置解析使用。选项Option说明--open [path]启动时自动打开浏览器boolean \| string--port port指定端口number--base path公共基础路径默认/string--cors启用 CORS--strictPort若指定端口已被占用则直接退出boolean--force强制优化器忽略缓存并重新打包依赖boolean参数背后的源码行为这些参数并非凭空生效而是被直接透传或转换为 Vite 的配置--base在 server.ts 中createServer会取出serverOptions.base若为字符串则调用normalizeSiteBase(base)后覆盖config.site.base再作为base传入 Vite 的createViteServer。--force在 cli.ts 中做了特殊处理——若传入--forceCLI 会将其删除并改写为argv.optimizeDeps { force: true }从而让 Vite 依赖优化器忽略缓存强制重新预构建。--port、--strictPort、--cors等会随serverOptions一并传入 Vite 的server配置项由 Vite 原生处理。布尔值参数如--cors会经过一个字符串到布尔值的归一化转换true/false字符串被转为真正的布尔值确保 minimist 解析出的结果符合预期。dev 服务器启动后会打印 VitePress 与底层 Vite 的版本信息见 logVersion.ts并输出可访问的 URL。开发服务器快捷键dev 服务器运行期间支持一组键盘快捷键实现在 shortcuts.ts 中按下h可随时查看帮助列表按键作用r重启开发服务器u再次打印服务器 URLo在浏览器中打开站点c清空控制台q退出开发服务器快捷键仅在终端为 TTY 且非 CI 环境时生效按CtrlC或CtrlD也会关闭服务器并退出进程。重启时CLI 会依次执行配置重新解析、释放 markdown-it 实例disposeMdItInstance、清除 markdown→Vue 转换缓存clearCache、关闭旧服务器并重新拉起新服务器从而保证配置改动后完全生效。vitepress build构建生产站点vitepress build用于将站点构建为可部署的生产版本输出静态 HTML 与资源文件到outDir。用法vitepress build [root]从 build.ts 的源码看build 流程会先后执行两阶段任务先building client server bundles客户端与 SSR 服务端打包再rendering pages渲染页面并可选地在配置了sitemap.hostname时生成 sitemap最后调用buildEnd钩子并清理临时目录输出build complete in xx.xxs.的耗时统计。构建期间还会临时把项目内的vue软链接到 VitePress 自带的 Vue除非用户已自行安装构建完成后自动解除链接。选项Option说明--mpa实验性以 MPA 模式 构建不进行客户端水合boolean--base path公共基础路径默认/string--assetsBase url生成资源所服务的基础 URL 前缀例如 CDN 地址string--target target转译目标默认modulesstring--outDir dir输出目录相对cwd默认root/.vitepress/diststring--assetsInlineLimit number静态资源 base64 内联阈值单位字节默认4096number参数在源码中的落点--mpa在 build.ts 中传入--mpa会直接置siteConfig.mpa true。MPA 模式Multi-Page Application下每个页面独立加载、不进行客户端水合适合对 SEO 与页面体积有极致要求的场景但会失去 SPA 式的页面内切换体验。该模式在 siteConfig.ts 中被标记为实验性experimental。--base需要携带值例如--base /docs/若未携带值会抛出--base requires a value (e.g. --base /docs/)错误。该值经normalizeSiteBase归一化后覆盖siteConfig.site.base。--assetsBase同样必须有值例如--assetsBase https://cdn.example.com/经normalizeAssetsBase处理后写入siteConfig.assetsBase可用于把静态资源托管到 CDN。assetsBasePlugin.ts 会基于此改写资源 URL并支持与experimental.renderBuiltUrl钩子配合做更精细的 URL 重写。--outDir注意其基准是cwd当前工作目录而非 root——源码中使用path.resolve(process.cwd(), buildOptions.outDir)解析而配置文件中outDir相对 root 解析。两者基准不同使用命令行参数时务必留意。--assetsInlineLimit与--target作为 Vite/Rolldown 的构建选项向下传递控制资源内联阈值默认 4096 字节小于等于该体积的资源会被内联为 base64与代码转译目标。vitepress preview本地预览生产构建vitepress preview在本地启动一个静态服务器用于预览vitepress build的构建产物。用法vitepress preview [root]其实现位于 serve.ts底层使用polkasirv默认监听端口为4173而非 dev 服务器常用的端口。服务会启用 gzip 压缩与 ETag 缓存静态资源位于assetsDir内、带指纹的文件设置maxAge31536000且immutable非资源 HTML 页面则强制cache-control: no-cache要求浏览器每次回源校验。选项Option说明--base path公共基础路径默认/string--assetsBase url生成资源所服务的基础 URL 前缀例如 CDN 地址string--port port指定端口number预览服务的行为细节相对 base 处理如果--base是相对路径如./预览服务会将其视为可在任意挂载点工作直接以/提供服务若是外部绝对 URL则取其 pathname 部分作为 base。404 处理请求未命中时若请求的是非资源路径会返回构建产物中的404.html这正是--mpa/静态托管场景下自定义 404 页面的来源否则返回空白 404。--assetsBase的两种情形若为外部 URLCDN预览服务会提示资源将从该 URL 请求而非本地若为本地路径前缀则会在该前缀下镜像一份资源子树方便本地验证。CLI 别名在 cli.ts 中serve与preview是等价的command serve || command preview走同一分支因此vitepress serve与vitepress preview行为一致。vitepress init交互式初始化向导vitepress init在当前目录启动 Setup Wizard以交互问答方式帮你快速搭好一个可直接运行的 VitePress 项目骨架。用法vitepress init也可以按包管理器执行npx vitepress init、pnpm vitepress init、yarn vitepress init或bun vitepress init参见 getting-started.md。向导会依次询问的问题实现位于 init.ts基于clack/prompts默认值与选项如下问题默认值 / 可选值说明在何处初始化 VitePress 配置./站点根目录从何处寻找 Markdown 文件同 root即srcDir站点标题My Awesome Project写入站点配置站点描述A VitePress Site写入站点配置主题默认主题 / 默认主题自定义 / 自定义主题三种脚手架深度是否用 TypeScript 编写配置与主题是/否决定生成.ts还是.js/.mjs是否向 package.json 注入 VitePress npm scripts是/否注入dev/build/preview脚本是否给 npm scripts 加前缀是/否如docs:dev脚本前缀名docs例如生成docs:dev向导会生成什么根据所选主题类型脚手架会写入不同文件集合默认主题index.md、api-examples.md、markdown-examples.md、.vitepress/config.js当前仓库 template 目录即这些模板的源默认主题 自定义额外生成.vitepress/theme/index.js与.vitepress/theme/style.css自定义主题额外再生成.vitepress/theme/Layout.vue。此外脚手架会智能处理若项目package.json非 ESM无type: module配置文件会生成.mjs扩展名若选择 TypeScript 则转为.ts/.mts。若选择了自定义主题但项目未安装vue向导会在结束时提示显式安装vue作为开发依赖若目录是 git 仓库还会提醒把.vitepress/dist与.vitepress/cache加入.gitignore。若选择注入 npm scripts则默认生成以docs前缀为例{ scripts: { docs:dev: vitepress dev docs, docs:build: vitepress build docs, docs:preview: vitepress preview docs } }完成后按提示运行pnpm run docs:dev或对应的包管理器命令即可开始写作。参数解析与命令分发的统一机制所有 CLI 参数统一由 cli.ts 顶部的minimist(process.argv.slice(2))解析随后经过一个关键归一化步骤所有值为字符串true或false的参数都会被转换为真正的布尔值避免--cors、--strictPort这类开关被当作字符串传入。命令分发逻辑如下dev或省略命令走开发服务器分支支持--force改写为optimizeDeps.force并绑定快捷键与重启逻辑init进入初始化向导init.tsbuild调用build(root, argv)执行生产构建serve/preview调用serve(argv)启动预览服务器serve.ts其他未知命令直接报错unknown command xxx并以退出码 1 结束。无论是配置解析失败、dev 启动失败、build 出错还是预览启动失败都会走logErrorAndExit统一打印错误含错误栈并process.exit(1)便于 CI 等自动化场景捕获失败状态。常见实战组合以下组合覆盖了日常高频场景# 1. 初始化文档项目 npx vitepress init # 2. 在 docs 目录启动开发服务器固定端口并自动打开浏览器 vitepress dev docs --port 5174 --open # 3. 使用自定义 base 路径构建部署到子路径 /guide/ vitepress build docs --base /guide/ # 4. 资源托管 CDN 的构建 vitepress build docs --assetsBase https://cdn.example.com/assets/ # 5. 指定输出目录相对当前工作目录 vitepress build docs --outDir ./dist # 6. MPA 模式构建实验性 vitepress build docs --mpa # 7. 本地预览构建产物指定端口 vitepress preview docs --port 8080总结VitePress 的 CLI 将「开发—构建—预览—初始化」四个阶段收敛为四个简洁命令dev提供带 HMR 与快捷键的开发体验build产出可部署的静态站点并支持--base、--assetsBase、--mpa、--outDir、--assetsInlineLimit等生产级选项preview基于构建产物做本地验证默认 4173 端口init则通过交互向导一站式完成项目脚手架搭建。理解这些命令与参数在源码中的落点cli.ts、server.ts、build.ts、serve.ts、init.ts将帮助你在实际项目中更精准地配置构建与部署流程。【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考