跳到主要内容

构建与启动文档站点

本文档介绍如何将 SkillFlaw 文档站点作为独立服务进行构建、预览与启动。

文档站点当前不再挂载在产品运行时的 /doc/ 路径下，而是以独立站点根路径提供服务。本地通常使用 http://localhost:3030/，部署环境中通常使用独立的文档域名或独立服务入口。

前置条件​

在执行文档站点相关命令前，请先确认：

  1. 当前目录位于仓库根目录；
  2. 本机已安装 Yarn；
  3. 已执行：

_10
make docs_install

文档系统统一使用 Yarn 作为包管理器，并将本地缓存放在 docs/.yarn-cache。

选择合适的工作流​

根据目标选择命令：

目标命令结果
以热更新方式预览文档源码改动make docs_dev启动 Docusaurus 开发服务器
生成静态文档产物make docs_build将生产构建输出写入 docs/build/
构建并立即启动独立文档站点make docs_serve构建 docs/build-standalone/ 并启动静态服务
仅启动已存在的文档产物，不重新构建make docs_start_only直接启动现有输出目录

启动开发预览服务​

当你在编辑文档源码并希望获得热更新预览时，使用：


_10
make docs_dev

默认行为：

  • 端口：3030
  • 路由形式：根路径 /
  • 使用场景：文档撰写与预览

访问地址：


_10
http://localhost:3030/

构建静态文档产物​

当你需要生成可独立托管的静态文档产物时，使用：


_10
make docs_build

该命令会：

  • 在需要时安装 docs 依赖；
  • 执行 Docusaurus 生产构建；
  • 将产物写入 docs/build/。

当后续会由其他静态托管服务、镜像构建流程或发布流程接管这些文件时，应使用该命令。

构建并启动独立文档站点​

当你希望先确保产物来自最新源码，再立即启动文档服务时，使用：


_10
make docs_serve

该命令会：

  • 将独立文档产物构建到 docs/build-standalone/；
  • 启动本地静态服务；
  • 以独立站点根路径提供文档访问。

当文档内容刚发生变化、且你希望启动前先完成重新构建时，应使用该命令。

仅启动已有产物，不重新构建​

当文档静态产物已经存在，而你只想快速把服务启动起来时，使用：


_10
make docs_start_only

默认情况下，该命令直接启动现有的 docs/build-standalone/ 目录，不会在启动前重新执行构建。

适用场景：

  • 文档已经在前一步完成构建；
  • 你只想快速重启 docs 服务；
  • 你要验证现有产物本身，而不是生成新的产物。

常用参数​

文档命令支持以下常用变量：

变量默认值用途
docs_port3030文档开发预览或静态服务启动端口
docs_serve_out_dirbuild-standalonemake docs_serve 使用的输出目录
docs_start_dirbuild-standalonemake docs_start_only 使用的现有产物目录
docs_base_url/make docs_dev 使用的基础路径
docs_build_base_url/make docs_build 使用的基础路径
docs_serve_base_url/make docs_serve 使用的基础路径

示例：


_10
make docs_dev docs_port=3040
_10
make docs_build docs_build_base_url=/
_10
make docs_serve docs_port=3040 docs_serve_out_dir=build-standalone
_10
make docs_start_only docs_port=3040 docs_start_dir=build-standalone

推荐使用方式​

编辑文档正文​

使用：


_10
make docs_dev

这是文档编写与实时预览的首选方式。

校验最新源码生成的独立站点​

使用：


_10
make docs_serve

该方式会先重新构建，再启动静态服务。

快速重启 docs 服务且保持产物不变​

使用：


_10
make docs_start_only

该方式不会触碰已有静态产物，只负责启动服务。

校验清单​

在将文档服务视为可用前，至少确认以下内容：

  • 文档站点通过独立根路径访问，而不是 /doc/；
  • 所选端口可正常访问；
  • 使用 make docs_start_only 前，目标产物目录已经存在；
  • 在重新构建后，中英文页面与链接均可正常访问。

另请参阅​