企业官网建设流程全解析

• 人工智能
• 机器学习
• 后端
• 编译器

SQLFlow（Brings SQL and AI together）是一个将 SQL 与机器学习融为一体的开源项目，其仓库内沉淀了大量技术文档，覆盖快速入门、环境搭建、设计文档与各类教程。随着文档数量增长（当前仓库根目录下已有 98 个 Markdown 文件），链接失效、路径错误等问题会直接损害文档的可信度与可维护性。本文基于仓库 scripts/markdown_link_check/README.md，完整讲解如何借助 markdown-link-check 工具对 SQLFlow 仓库的 Markdown 文档进行链接健康检查：从安装、单文件校验、全量扫描到配置文件定制，并结合仓库 scripts/markdown_link_check/config.json 与现有文档中的链接形态，给出可直接落地的操作方案。

markdown-link-check 是什么

markdown-link-check 是一个用于检测 Markdown 文件中链接是否可访问的命令行工具。SQLFlow 项目使用它作为文档质量保障手段，正如 scripts/markdown_link_check/README.md 开头所述："We use markdown-link-check to check all the links in the markdown files."

它能够对 Markdown 文本中的两类链接进行检查：

• 外部链接：如指向阿里云 MaxCompute 官方文档、GitHub 页面等以http(s)://开头的 URL，工具会发起实际请求以验证其可达性；
• 站内/仓库内链接：如文档中以/doc/...形式书写的仓库根路径相对链接，工具会基于配置文件中的替换规则转换后检查其有效性。

对于 SQLFlow 这类同时包含大量外部云平台文档链接与仓库内部设计文档交叉引用（例如 doc/design/codegen.md 中的/doc/design/workflow.md、doc/design/intermediate_representation.md 中的/pkg/codegen/intermediate_representation.go）的仓库而言，这种自动化检查能显著降低人工核对成本。

安装：环境准备与前置要求

工具的安装依赖 Node.js 生态的 npm 包管理器。官方安装命令为全局安装，在终端中执行：

npm install -g markdown-link-check

几点说明：

• -g表示全局安装，安装后markdown-link-check命令即可在任意目录直接调用；
• 如果希望限定在项目内使用，也可以去掉-g改为项目级安装，此时需要配合 npx 或 node_modules 路径调用；
• 文档中特别注明该安装命令适用于 Mac（"To install on your Mac"），在 Linux 环境（如本项目常见的 CI 场景）下，安装方式同样适用，只需确保系统已具备 Node.js 与 npm 运行时；
• 该工具是基于 tcort/markdown-link-check 的开源命令行实现，SQLFlow 将其作为文档检查的标准工具，仓库 scripts/markdown_link_check 目录下存放了配套的检查配置。

单文件检查：从指定文档开始

安装完成后，进入 SQLFlow 仓库根目录，即可对单个 Markdown 文件执行链接检查。以文档中给出的示例为例：

$ markdown-link-check doc/run_with_maxcompute.md -c scripts/markdown_link_check/config.json

命令拆解：

• doc/run_with_maxcompute.md：被检查的 Markdown 文件路径，这里选中的是一篇介绍如何在 SQLFlow 中连接并使用阿里云 MaxCompute（a.k.a ODPS）的教程；
• -c scripts/markdown_link_check/config.json：指定检查配置文件。该参数将仓库定制的规则注入工具，包括链接忽略与替换规则；
• 命令前需进入项目根目录执行（文档明确要求 "enter the following in the project root directory"），因为配置文件的相对路径以仓库根为基准。

配置文件 scripts/markdown_link_check/config.json 的实际内容如下：

{ "ignorePatterns": [ { "pattern": "^http://example.net" } ], "replacementPatterns": [ { "pattern": "^/", "replacement": "https://github.com/sql-machine-learning/sqlflow/tree/develop/" } ] }

其语义可以结合仓库文档中的真实链接形态来理解：

• ignorePatterns（忽略规则）：以^http://example.net开头的链接将被跳过检查。example.net是 RFC 预留的示例域名，本身不可访问，文档中若出现此类占位示例链接（比如http://example.net/some-page），检查工具会直接忽略，避免误报；
• replacementPatterns（替换规则）：所有以/开头的链接会被替换为https://github.com/sql-machine-learning/sqlflow/tree/develop/前缀。这正是 SQLFlow 文档中大量使用的根路径相对链接写法——例如 doc/design/couler_sqlflow.md 中的[Intermediate Representation](https://link.gitcode.com/i/ab5418b46ef7883622f50823ee27c77c)、doc/design/katib_on_sqlflow.md 中的intermediate representation。经过替换后，/doc/design/workflow.md会被解析为https://github.com/sql-machine-learning/sqlflow/tree/develop/doc/design/workflow.md，从而让工具能够验证这些站内链接是否真实存在。

输出解读：如何阅读检查报告

执行单文件检查后，工具会逐条输出结果。文档中给出的示例输出如下：

FILE: doc/run_with_maxcompute.md [✓] https://www.alibabacloud.com/product/maxcompute [✓] https://usercenter.console.aliyun.com/#/manage/ak [✓] https://workbench.data.aliyun.com/console?#/ [✓] https://www.alibabacloud.com/help/doc-detail/34951.htm [✓] https://workbench.data.aliyun.com/console#/ [✓] https://www.alibabacloud.com/help/doc-detail/74293.htm

输出格式解读：

• 第一行FILE:标明当前检查的文件，便于在多文件批量输出中定位问题；
• 每行一个被检查的链接，[✓]表示该链接可正常访问；
• 若链接失效，则会以[✗]标记并附带 HTTP 状态码或错误信息，需要据此定位并修复。

对照 doc/run_with_maxcompute.md 的正文可以发现，上述输出中的链接正是该文档中引用阿里云官方资料的 6 个外部链接：MaxCompute 产品页、阿里云 AccessKey 用户中心、MaxCompute 工作台、Endpoint 配置文档、工作区设置与 Create Workspace 教程。这验证了检查结果与文档内容的对应关系——凡文档中出现的外部链接都会被逐一验证。

全量扫描：一次性检查全部 Markdown 文件

SQLFlow 仓库中的文档分布在 doc、README.md 等多个位置，逐一检查效率过低。文档给出了批量扫描方案：

find . -name \*.md -exec markdown-link-check -c scripts/markdown_link_check/config.json {} \;

命令拆解：

• find . -name \*.md：递归查找当前目录（含子目录）下所有扩展名为.md的文件。在 SQLFlow 仓库中，这会覆盖 doc 下的入门指南、设计文档（doc/design）、中文站文档（doc/sqlflow.org_cn）、教程（doc/tutorial）以及根目录 README.md 等全部 Markdown 文件；
• -exec ... {} \;：对每个找到的文件依次执行markdown-link-check -c scripts/markdown_link_check/config.json，其中{}被替换为文件路径；
• \;是 find 的-exec终止符，表示每条命令单独执行，确保任意文件检查失败不会中断后续文件（与+批量传参的差异点在于此）。

批量扫描适用于两类场景：

1. 提交前自检：开发者在改动文档后，全量扫描可以第一时间暴露被破坏的链接；
2. CI 集成：将上述命令接入持续集成流水线，当任一 Markdown 链接失效时即让构建失败，从流程上杜绝"文档悄悄腐化"。

注意：仓库根目录共有 98 个 Markdown 文件，全量检查会发起大量外链请求，耗时取决于网络状况；若只想快速验证局部改动，建议先使用单文件检查命令。

配置进阶：让检查贴合仓库实际

SQLFlow 的检查配置只用了 ignorePatterns 与 replacementPatterns 两个核心字段，但理解其设计思路有助于按需扩展：

• ignorePatterns：用于豁免特定链接。除示例域名外，常见的豁免对象还包括：需要登录鉴权才能访问的私有链接、频繁变更的临时地址、以及工具本身不支持的非 HTTP 协议链接（如mailto:、tel:等）。注意ignorePatterns与replacementPatterns中的pattern均按正则表达式匹配；
• replacementPatterns：用于链接改写，^/规则解决了 SQLFlow 文档中"以仓库根为基准的站内链接"的校验问题。如果未来仓库文档改用其他基准路径，只需调整该规则的pattern与replacement即可，无需改动文档本身；
• 配置文件以 JSON 格式组织，位于仓库 scripts/markdown_link_check/config.json，与说明文档 scripts/markdown_link_check/README.md 同目录存放，集中管理便于团队统一维护检查口径。

排查与修复：链接失效后的处理思路

结合工具输出与仓库文档实际，链接失效通常来自以下几类原因，修复时可逐项排查：

1. 外部链接失效：目标页面被删除、域名变更或加入防爬校验。此时应从[✗]输出中确认具体 URL，更新 doc 下对应文档中的链接为新的官方地址；
2. 站内根路径链接不匹配：文档中书写了不存在的仓库路径（例如写错文件名或目录层级）。SQLFlow 文档大量使用/doc/...、/pkg/...形式（如 doc/design/katib_on_sqlflow.md 中的/pkg/sql/ir），这类错误可通过核对仓库实际目录树快速定位，确认后再修正文档中的链接文本；
3. 配置规则未覆盖：若站内链接不是以/开头（而是相对路径或带./、../前缀），当前^/替换规则不会生效，需要视情况补充 replacementPatterns 规则；
4. 网络导致的偶发失败：外链检查依赖实时网络请求，偶发超时也会产生[✗]，可重跑单文件命令复核后再决定是否修复。

小结

SQLFlow 将 markdown-link-check 作为文档质量的常规检查手段，通过 scripts/markdown_link_check/config.json 实现"忽略示例域名、改写站内根路径链接"的定制行为，以单文件命令支撑日常开发、以 find 批量命令支撑全量扫描与 CI 集成。这套方案的技术要点可归纳为：

• 安装：npm install -g markdown-link-check；
• 单文件检查：markdown-link-check <file> -c scripts/markdown_link_check/config.json（在仓库根目录执行）；
• 全量检查：find . -name \*.md -exec markdown-link-check -c scripts/markdown_link_check/config.json {} \;；
• 配置定制：通过 ignorePatterns 豁免特定链接、通过 replacementPatterns 处理仓库内根路径链接；
• 输出解读：[✓]表示链接有效，[✗]表示失效，需结合文档内容定位修复。

对于任何依赖大量文档的软件仓库，将链接检查纳入日常开发与 CI 流程，都是维持文档长期可用性的低成本高收益实践。

• 人工智能
• 机器学习
• 后端
• 编译器