Solana 文档站工程实践Docusaurus 本地构建、CLI 文档生成与 CI 发布流程详解【免费下载链接】solanaWeb-Scale Blockchain for fast, secure, scalable, decentralized apps and marketplaces.项目地址: https://gitcode.com/GitHub_Trending/so/solana本文基于 Solana 仓库中的 docs/README.md 展开系统讲解 Solana Validator 文档站的本地开发环境搭建npm install→./build.sh→npm run start、构建脚本背后的三条关键流水线CLI 用法文档生成、ASCII 图转 SVG、Crowdin 多语言同步以及 PR 构建与按分支发布到不同文档域名的 CI 流程。读完本文你将能够独立在本地拉起并维护该文档站定位 Bad sidebars file、Docker 权限、SVG 缺失三类常见构建故障并理解docs目录下各脚本与ci工具链之间的真实调用关系。文档站的定位Validator 客户端文档而非协议通识文档docs/README.md 开宗明义地划定了本站的内容边界本仓库docs/目录下的文档专门聚焦于 Solana Labs 维护的 Solana validator 客户端而面向 Solana 协议整体、适用于所有 validator 实现的通识性文档则维护在独立的developer-content外部仓库中由 Solana Foundation 管理。这一划分决定了本文所有操作的对象docs/src/下的 CLI 指南、验证器运维、共识原理与架构等页面而不是协议层通识内容。技术栈上文档站由Docusaurus v2构建、使用npm管理依赖静态内容托管经由Vercel完成。从 docs/package.json 可以确认具体依赖与可用脚本核心依赖docusaurus/core/docusaurus/preset-classic^2.2.0、crowdin/cli^3.17.0、remark-math与rehype-katexLaTeX 公式渲染、docusaurus/theme-search-algolia站内搜索。关键 npm scriptsstart启动本地开发服务器、build静态构建、write-heading-ids、write-translations、write-i18n前两者组合、crowdin:download、crowdin:upload先执行write-i18n再上传。这些脚本是理解后续各节命令的基础——README 中出现的npm run start、npm run crowdin:download等均定义于该文件。本地开发环境搭建三步命令与前置约束README 给出的本地开发流程只有三步全部在docs/目录内执行克隆仓库后不要跑到仓库根目录执行# 1. 安装依赖 npm install # 2. 本地构建生成静态内容到 build 目录同时也是必需的前置步骤 ./build.sh # 3. 启动 Docusaurus 本地开发服务器并自动打开浏览器 npm run start其中./build.sh是承上启下的关键步骤README 特别强调在执行npm run start之前必须先跑通构建脚本因为它负责生成被侧边栏引用的cli/usage.md文档缺失时开发服务器会直接报错详见后文Bad sidebars file故障一节。构建产物是纯静态内容输出到build目录可以用任意静态托管服务分发。另外注意大多数改动在开发服务器中实时生效无需重启或刷新但部分改动仍需手动刷新页面甚至通过npm run start重启开发服务器。构建脚本 build.sh 的完整调用链./build.sh远不止一句npm run build。逐行阅读 docs/build.sh 可知其执行链如下source ../ci/env.sh # 加载 CI 环境变量 source ../ci/rust-version.sh # 解析仓库锁定的 Rust 工具链版本 ../ci/docker-run-default-image.sh docs/build-cli-usage.sh # Docker 内生成 CLI 用法文档 ../ci/docker-run-default-image.sh docs/convert-ascii-to-svg.sh # 转换 art/*.bob 为 SVG ./set-solana-release-tag.sh # 设置 Solana 发布版本标识 eval $(../ci/channel-info.sh) # 判定当前分支所属 channeledge/beta/stable之后是两条条件分支仅 stable channel 同步翻译见 docs/build.sh#L18-L23当channel-info.sh判定当前为stable时自动执行npm run crowdin:download与npm run crowdin:upload与 Crowdin 平台双向同步译文。仅 CI 合入构建才发布见 docs/build.sh#L30-L38在 CI 环境$CI非空且非 Pull Request 构建时若存在 tag 且不是 beta 系列 tag 则直接退出否则调用 docs/publish-docs.sh 执行 Vercel 生产部署。这里有两个值得注意的工程细节Docker 是硬依赖构建脚本会通过ci/docker-run-default-image.sh自动拉取solanalabs/rust镜像在容器内从源码编译指定版本的 Solana CLI。没有可用 Docker 守护进程时构建必然失败对应后文Permission denied for the Docker socket故障。发布策略内建于脚本PR 构建只编译不发布只有合入后的提交与特定的 release tag 构建才会真正走到publish-docs.sh这保证了未评审的文档改动不会污染线上站点。核心流水线一从 solana-cli 源码生成 cli/usage.md文档站中最特别的一份页面是src/cli/usage.md——它不是人工撰写的而是由 docs/build-cli-usage.sh 从solana-clicrate 的运行输出中自动提取生成因此该文件被列入了.gitignore。脚本的关键动作见 docs/build-cli-usage.sh#L27-L63# 先用 stable 版 Rust 工具链预编译 CLI也用于避免 CI 挂起检测 cargo build -p solana-cli # 抓取顶层帮助输出并把 $HOME 替换为 ~、去除行尾空白 usage$(cargo -q run -p solana-cli -- -C ~/.foo --help | sed ...) # 解析顶层帮助中的 SUBCOMMANDS: 段落 # 对每个子命令再执行 cargo -q run -p solana-cli -- help subcommand # 逐一写入独立小节### 标题 text 代码块也就是说文档站展示的每条 Solana CLI 命令的用法、参数、子命令列表都与源码中的 clap 定义严格同源——CLI 参数一旦变更重新构建文档站即可自动同步。这一点对于维护者极其重要手工编辑usage.md毫无意义因为它每次构建都会被覆盖。脚本还包含一个 CI 优化分支当CI环境变量非空、且当前分支既不是 edge、beta 也不是 stable 渠道分支时跳过耗时的真实生成仅写入一行该用法文档仅在正式部署时自动生成的占位说明见 docs/build-cli-usage.sh#L18-L25避免非部署型 PR 构建浪费时间。核心流水线二ASCII 图 art/*.bob 转 SVGdocs/convert-ascii-to-svg.sh 负责把docs/art/下的文本图源码转换为站点实际引用的图片输出目录为static/img见 docs/convert-ascii-to-svg.sh#L9-L27art/*.bob使用svgbob_cli或svgbob二进制转换为同名.svgart/*.msc使用mscgen -T png转换为同名.png消息序列图。docs/art/目录下的素材覆盖了文档站的核心架构配图例如 tpu.bob、tvu.bob、validator.bob、fork-generation.bob、turbine 相关的 retransmit_stage.bob 以及 passive-staking-callflow.msc 等。正文 Markdown 中引用的即这些转换产物static/img/*.svg这也是后文Multiple SVG images not found故障的直接原因本地从未执行过该转换。Crowdin 翻译体系token、脚本与 stable 渠道策略README 的 Translations 一节说明了文档站的多语言方案结合仓库文件可以还原完整机制1. 配置文件docs/crowdin.yml声明了 Crowdin 项目project_id: 2、token 环境变量名CROWDIN_PERSONAL_TOKEN以及三类同步对象——/i18n/en/**下的 JSON 翻译文件、/src/**/*.md与/src/**/*.mdx文档正文、/src/**/*.json的侧边栏分类文件preserve_hierarchy: true保持目录层级。2. 本地开发两条命令需在docs/目录执行且已设置CROWDIN_PERSONAL_TOKEN环境变量Crowdin CLI 会自动读取.env文件中的值# 下载最新译文 npm run crowdin:download # 上传 src 的变更并先生成显式标题 IDheading IDs npm run crowdin:upload对照 docs/package.json 可见crowdin:upload实际是npm run write-i18n crowdin upload即先执行 Docusaurus 的write-heading-ids与write-translations再生成显式锚点 ID 后上传——显式 ID 的作用是保证标题重命名/移动不破坏翻译文件的锚点关联。3. 仅 stable 渠道包含译文README 明确说明翻译内容只在构建STABLE渠道文档时随build.sh注入因此只有面向最新发布版的文档站会包含译文edge与beta两个文档站不预期包含译文即使语言选择器依然存在。这与 docs/build.sh#L18-L23 中if [ $CHANNEL stable ]的分支完全对应。4. 已知无法构建的语言某些语言的符号会被 Docusaurus 静态生成器以SyntaxError解析失败而任何一个 locale 构建失败都会导致整个文档站构建失败、无法部署。当前无法构建的 locale 名单以注释形式记录在 docs/docusaurus.config.js 的localesNotBuilding属性中当前为ko、pt、vi、zh、ja实际启用的 locale 为en、de、es、ru、ar见i18n.locales配置。CI 构建与发布流程PR 只构建合入按分支发布README 描述的 CI 流程与仓库脚本对应关系如下每次 PR执行./build.sh构建文档但不发布对应build.sh中CI_PULL_REQUEST非空时不进入发布分支。每次合入后的构建文档按构建分支发布到对应域名README 给出的映射为构建来源发布目标README 描述master 分支edge.docs.solanalabs.combeta 分支beta.docs.solanalabs.com最新 release tagdocs.solanalabs.com从 docs/publish-docs.sh 的实现看发布时会根据CI_TAG与channel-info.sh判定的渠道动态生成一份vercel.json含大量历史路径 301 重定向规则把旧文档路径如/running-validator/...、/cli/delegate-stake等重定向到现路径或协议站新地址然后执行vercel deploy . --local-configvercel.json --confirm --token $VERCEL_TOKEN --prod即要求 CI 环境配置了VERCEL_TOKEN缺失时脚本直接报错退出与VERCEL_SCOPE两个凭据tag 构建对应正式发布项目beta 与 edge 分支则分别映射到各自独立的 Vercel 项目。这套机制保证了三个渠道的文档站彼此隔离、互不覆盖。常见故障排查Common IssuesREADME 最后整理了三类高频故障结合脚本实现可以给出更明确的定位路径1. Bad sidebars file或 cli/usage not found报错形如Error: Bad sidebars file. These sidebar document ids do not exist: - cli/usage,根因cli/usage.md由构建生成且位于.gitignore中未成功跑过构建脚本的本地仓库就没有这个文档而 docs/sidebars.js 又引用了它。解决方案按本地工具链条件二选一本机已安装 Rust 工具链尤其cargo直接运行./build-cli-usage.sh单独生成该文档否则用 Docker 跑完整的./build.sh生产式构建。2. Permission denied for the Docker socketGot permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post./build.sh强依赖 Docker。先确认本机 Docker 已安装且守护进程在运行仍失败时可用提权方式执行构建脚本sudo ./build.sh # 或 sudo ./build-cli-usage.sh3. Multiple SVG images not foundError: Image static/img/***.svg used in src/***.md not found.这是未运行./build.sh中convert-ascii-to-svg.sh步骤的典型症状art/*.bob尚未转换为static/img下的 SVG。按本地构建流程补跑构建即可。README 补充说明缺少这些 SVG不会阻止本地开发服务器启动但终端会刷出大量报错保持转换产物齐全可避免干扰。小结docs/README.md 虽然篇幅不长却完整刻画了一个文档即构建产物的工程体系CLI 用法文档与源码同源自动生成架构图以可维护的 ASCII 源码形式入库多语言走 Crowdin 且只在 stable 渠道生效发布按 edge/beta/stable 三渠道隔离。想进一步深入建议按以下顺序阅读仓库文件docs/build.sh 与 docs/build-cli-usage.sh构建主链路、docs/convert-ascii-to-svg.sh配图流水线、docs/crowdin.yml 与 docs/docusaurus.config.jsi18n 与站点配置、docs/publish-docs.shVercel 发布与历史路径重定向以及 docs/sidebars.js站点导航结构定义。【免费下载链接】solanaWeb-Scale Blockchain for fast, secure, scalable, decentralized apps and marketplaces.项目地址: https://gitcode.com/GitHub_Trending/so/solana创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Solana 文档站工程实践：Docusaurus 本地构建、CLI 文档生成与 CI 发布流程详解
Solana 文档站工程实践Docusaurus 本地构建、CLI 文档生成与 CI 发布流程详解【免费下载链接】solanaWeb-Scale Blockchain for fast, secure, scalable, decentralized apps and marketplaces.项目地址: https://gitcode.com/GitHub_Trending/so/solana本文基于 Solana 仓库中的 docs/README.md 展开系统讲解 Solana Validator 文档站的本地开发环境搭建npm install→./build.sh→npm run start、构建脚本背后的三条关键流水线CLI 用法文档生成、ASCII 图转 SVG、Crowdin 多语言同步以及 PR 构建与按分支发布到不同文档域名的 CI 流程。读完本文你将能够独立在本地拉起并维护该文档站定位 Bad sidebars file、Docker 权限、SVG 缺失三类常见构建故障并理解docs目录下各脚本与ci工具链之间的真实调用关系。文档站的定位Validator 客户端文档而非协议通识文档docs/README.md 开宗明义地划定了本站的内容边界本仓库docs/目录下的文档专门聚焦于 Solana Labs 维护的 Solana validator 客户端而面向 Solana 协议整体、适用于所有 validator 实现的通识性文档则维护在独立的developer-content外部仓库中由 Solana Foundation 管理。这一划分决定了本文所有操作的对象docs/src/下的 CLI 指南、验证器运维、共识原理与架构等页面而不是协议层通识内容。技术栈上文档站由Docusaurus v2构建、使用npm管理依赖静态内容托管经由Vercel完成。从 docs/package.json 可以确认具体依赖与可用脚本核心依赖docusaurus/core/docusaurus/preset-classic^2.2.0、crowdin/cli^3.17.0、remark-math与rehype-katexLaTeX 公式渲染、docusaurus/theme-search-algolia站内搜索。关键 npm scriptsstart启动本地开发服务器、build静态构建、write-heading-ids、write-translations、write-i18n前两者组合、crowdin:download、crowdin:upload先执行write-i18n再上传。这些脚本是理解后续各节命令的基础——README 中出现的npm run start、npm run crowdin:download等均定义于该文件。本地开发环境搭建三步命令与前置约束README 给出的本地开发流程只有三步全部在docs/目录内执行克隆仓库后不要跑到仓库根目录执行# 1. 安装依赖 npm install # 2. 本地构建生成静态内容到 build 目录同时也是必需的前置步骤 ./build.sh # 3. 启动 Docusaurus 本地开发服务器并自动打开浏览器 npm run start其中./build.sh是承上启下的关键步骤README 特别强调在执行npm run start之前必须先跑通构建脚本因为它负责生成被侧边栏引用的cli/usage.md文档缺失时开发服务器会直接报错详见后文Bad sidebars file故障一节。构建产物是纯静态内容输出到build目录可以用任意静态托管服务分发。另外注意大多数改动在开发服务器中实时生效无需重启或刷新但部分改动仍需手动刷新页面甚至通过npm run start重启开发服务器。构建脚本 build.sh 的完整调用链./build.sh远不止一句npm run build。逐行阅读 docs/build.sh 可知其执行链如下source ../ci/env.sh # 加载 CI 环境变量 source ../ci/rust-version.sh # 解析仓库锁定的 Rust 工具链版本 ../ci/docker-run-default-image.sh docs/build-cli-usage.sh # Docker 内生成 CLI 用法文档 ../ci/docker-run-default-image.sh docs/convert-ascii-to-svg.sh # 转换 art/*.bob 为 SVG ./set-solana-release-tag.sh # 设置 Solana 发布版本标识 eval $(../ci/channel-info.sh) # 判定当前分支所属 channeledge/beta/stable之后是两条条件分支仅 stable channel 同步翻译见 docs/build.sh#L18-L23当channel-info.sh判定当前为stable时自动执行npm run crowdin:download与npm run crowdin:upload与 Crowdin 平台双向同步译文。仅 CI 合入构建才发布见 docs/build.sh#L30-L38在 CI 环境$CI非空且非 Pull Request 构建时若存在 tag 且不是 beta 系列 tag 则直接退出否则调用 docs/publish-docs.sh 执行 Vercel 生产部署。这里有两个值得注意的工程细节Docker 是硬依赖构建脚本会通过ci/docker-run-default-image.sh自动拉取solanalabs/rust镜像在容器内从源码编译指定版本的 Solana CLI。没有可用 Docker 守护进程时构建必然失败对应后文Permission denied for the Docker socket故障。发布策略内建于脚本PR 构建只编译不发布只有合入后的提交与特定的 release tag 构建才会真正走到publish-docs.sh这保证了未评审的文档改动不会污染线上站点。核心流水线一从 solana-cli 源码生成 cli/usage.md文档站中最特别的一份页面是src/cli/usage.md——它不是人工撰写的而是由 docs/build-cli-usage.sh 从solana-clicrate 的运行输出中自动提取生成因此该文件被列入了.gitignore。脚本的关键动作见 docs/build-cli-usage.sh#L27-L63# 先用 stable 版 Rust 工具链预编译 CLI也用于避免 CI 挂起检测 cargo build -p solana-cli # 抓取顶层帮助输出并把 $HOME 替换为 ~、去除行尾空白 usage$(cargo -q run -p solana-cli -- -C ~/.foo --help | sed ...) # 解析顶层帮助中的 SUBCOMMANDS: 段落 # 对每个子命令再执行 cargo -q run -p solana-cli -- help subcommand # 逐一写入独立小节### 标题 text 代码块也就是说文档站展示的每条 Solana CLI 命令的用法、参数、子命令列表都与源码中的 clap 定义严格同源——CLI 参数一旦变更重新构建文档站即可自动同步。这一点对于维护者极其重要手工编辑usage.md毫无意义因为它每次构建都会被覆盖。脚本还包含一个 CI 优化分支当CI环境变量非空、且当前分支既不是 edge、beta 也不是 stable 渠道分支时跳过耗时的真实生成仅写入一行该用法文档仅在正式部署时自动生成的占位说明见 docs/build-cli-usage.sh#L18-L25避免非部署型 PR 构建浪费时间。核心流水线二ASCII 图 art/*.bob 转 SVGdocs/convert-ascii-to-svg.sh 负责把docs/art/下的文本图源码转换为站点实际引用的图片输出目录为static/img见 docs/convert-ascii-to-svg.sh#L9-L27art/*.bob使用svgbob_cli或svgbob二进制转换为同名.svgart/*.msc使用mscgen -T png转换为同名.png消息序列图。docs/art/目录下的素材覆盖了文档站的核心架构配图例如 tpu.bob、tvu.bob、validator.bob、fork-generation.bob、turbine 相关的 retransmit_stage.bob 以及 passive-staking-callflow.msc 等。正文 Markdown 中引用的即这些转换产物static/img/*.svg这也是后文Multiple SVG images not found故障的直接原因本地从未执行过该转换。Crowdin 翻译体系token、脚本与 stable 渠道策略README 的 Translations 一节说明了文档站的多语言方案结合仓库文件可以还原完整机制1. 配置文件docs/crowdin.yml声明了 Crowdin 项目project_id: 2、token 环境变量名CROWDIN_PERSONAL_TOKEN以及三类同步对象——/i18n/en/**下的 JSON 翻译文件、/src/**/*.md与/src/**/*.mdx文档正文、/src/**/*.json的侧边栏分类文件preserve_hierarchy: true保持目录层级。2. 本地开发两条命令需在docs/目录执行且已设置CROWDIN_PERSONAL_TOKEN环境变量Crowdin CLI 会自动读取.env文件中的值# 下载最新译文 npm run crowdin:download # 上传 src 的变更并先生成显式标题 IDheading IDs npm run crowdin:upload对照 docs/package.json 可见crowdin:upload实际是npm run write-i18n crowdin upload即先执行 Docusaurus 的write-heading-ids与write-translations再生成显式锚点 ID 后上传——显式 ID 的作用是保证标题重命名/移动不破坏翻译文件的锚点关联。3. 仅 stable 渠道包含译文README 明确说明翻译内容只在构建STABLE渠道文档时随build.sh注入因此只有面向最新发布版的文档站会包含译文edge与beta两个文档站不预期包含译文即使语言选择器依然存在。这与 docs/build.sh#L18-L23 中if [ $CHANNEL stable ]的分支完全对应。4. 已知无法构建的语言某些语言的符号会被 Docusaurus 静态生成器以SyntaxError解析失败而任何一个 locale 构建失败都会导致整个文档站构建失败、无法部署。当前无法构建的 locale 名单以注释形式记录在 docs/docusaurus.config.js 的localesNotBuilding属性中当前为ko、pt、vi、zh、ja实际启用的 locale 为en、de、es、ru、ar见i18n.locales配置。CI 构建与发布流程PR 只构建合入按分支发布README 描述的 CI 流程与仓库脚本对应关系如下每次 PR执行./build.sh构建文档但不发布对应build.sh中CI_PULL_REQUEST非空时不进入发布分支。每次合入后的构建文档按构建分支发布到对应域名README 给出的映射为构建来源发布目标README 描述master 分支edge.docs.solanalabs.combeta 分支beta.docs.solanalabs.com最新 release tagdocs.solanalabs.com从 docs/publish-docs.sh 的实现看发布时会根据CI_TAG与channel-info.sh判定的渠道动态生成一份vercel.json含大量历史路径 301 重定向规则把旧文档路径如/running-validator/...、/cli/delegate-stake等重定向到现路径或协议站新地址然后执行vercel deploy . --local-configvercel.json --confirm --token $VERCEL_TOKEN --prod即要求 CI 环境配置了VERCEL_TOKEN缺失时脚本直接报错退出与VERCEL_SCOPE两个凭据tag 构建对应正式发布项目beta 与 edge 分支则分别映射到各自独立的 Vercel 项目。这套机制保证了三个渠道的文档站彼此隔离、互不覆盖。常见故障排查Common IssuesREADME 最后整理了三类高频故障结合脚本实现可以给出更明确的定位路径1. Bad sidebars file或 cli/usage not found报错形如Error: Bad sidebars file. These sidebar document ids do not exist: - cli/usage,根因cli/usage.md由构建生成且位于.gitignore中未成功跑过构建脚本的本地仓库就没有这个文档而 docs/sidebars.js 又引用了它。解决方案按本地工具链条件二选一本机已安装 Rust 工具链尤其cargo直接运行./build-cli-usage.sh单独生成该文档否则用 Docker 跑完整的./build.sh生产式构建。2. Permission denied for the Docker socketGot permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post./build.sh强依赖 Docker。先确认本机 Docker 已安装且守护进程在运行仍失败时可用提权方式执行构建脚本sudo ./build.sh # 或 sudo ./build-cli-usage.sh3. Multiple SVG images not foundError: Image static/img/***.svg used in src/***.md not found.这是未运行./build.sh中convert-ascii-to-svg.sh步骤的典型症状art/*.bob尚未转换为static/img下的 SVG。按本地构建流程补跑构建即可。README 补充说明缺少这些 SVG不会阻止本地开发服务器启动但终端会刷出大量报错保持转换产物齐全可避免干扰。小结docs/README.md 虽然篇幅不长却完整刻画了一个文档即构建产物的工程体系CLI 用法文档与源码同源自动生成架构图以可维护的 ASCII 源码形式入库多语言走 Crowdin 且只在 stable 渠道生效发布按 edge/beta/stable 三渠道隔离。想进一步深入建议按以下顺序阅读仓库文件docs/build.sh 与 docs/build-cli-usage.sh构建主链路、docs/convert-ascii-to-svg.sh配图流水线、docs/crowdin.yml 与 docs/docusaurus.config.jsi18n 与站点配置、docs/publish-docs.shVercel 发布与历史路径重定向以及 docs/sidebars.js站点导航结构定义。【免费下载链接】solanaWeb-Scale Blockchain for fast, secure, scalable, decentralized apps and marketplaces.项目地址: https://gitcode.com/GitHub_Trending/so/solana创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考