简介Ant Design 4.1.5 离线文档包面向网络受限或内网环境中的前端工程师与中后台项目组文档版本更新至 4.20.2涵盖自 4.1.5 以来的组件增强、API 调整与变更记录可避免在线查阅时的加载等待。压缩包共 576 个文件含 297 个 JS 脚本、276 个 HTML 页面与 3 个 CSS 样式表整体仅 8.21 MB其中 HTML 构成文档页面骨架JS 驱动组件示例与交互效果CSS 则提供深色与紧凑主题样式可部署至本地 Apache 后通过浏览器随时访问也便于团队成员共享查阅。包内提供中英文主页、详细变更日志以及按钮、表格、布局、表单等核心组件的完整 API 参考、属性说明与实际示例方便开发者离线核对组件属性、方法、事件并快速掌握升级与配置要点。已有 3975 人学习下载适合需要快速搭建离线文档站点的个人开发者或团队作为稳定的前端知识库使用。 最近在帮一个项目组整理前端基建发现好几个同事都用同一个很原始的操作把 Ant Design 官网按 CtrlS 存成本地页面凑合着查组件 API翻一页卡半天。问下来倒不是大家懒得打字而是这个项目跑在完全隔离的内网开发环境外网根本访问不了。后来我花了半个下午把仓库里 4.1.5 版本的源码拉下来构建了一份真正自包含的 Ant Design 4.1.5 离线版本文档部署到内网服务器之后整个团队查组件再也不用靠截图和聊天记录过日子了。这篇文章就把整个思路、选型过程和踩过的坑完整记录下来。不管你是被困在内网的前端开发还是要给团队做工具链沉淀的基建负责人照着做基本都能复现一份属于自己的离线文档。顺便要提醒一句本文讲的是在合法、合规的内网隔离环境下部署开源组件的本地文档整个流程不涉及任何非常规网络手段。1. 为什么一个正常的前端团队会需要离线文档先说结论离线文档不是没有外网才需要的备胎它本质上是一种版本快照是把文档和依赖版本死死绑在一起的手段。我见过太多团队package.json 里锁的是 4.1.5打开官网查到的却是已经更新换代的最新版API 早就不一样了照着官网写出来的代码在本地编译直接报错。1.1 官网文档在真实项目里的三个失灵场景第一安全隔离环境。不少涉及敏感数据的项目开发机只能访问内网资源npm 包可以从内网镜像拉但文档站点属于外网资源一律不可达。这种环境下别说什么便捷体验连最基本的组件参数都查不到。第二线上文档版本漂移。Ant Design 这类活跃组件库官网永远展示的是最新版本或者预发布版本的内容。哪怕你只是想确认一个 4.x 的 Form 校验规则写法打开官网看到的可能是 5.x 甚至 rc 版本的推荐用法。如果对版本差异不够敏感照抄出来的代码要么弃用警告满天飞要么行为完全不符合预期。第三网络不稳定导致的中断式查询。就算能上外网文档站点的字体、图标、搜索请求全部依赖外部 CDN网络一波动页面框架出来了内容却在转圈。一个 API 参数查 5 分钟效率非常难看。1.2 把文档视为和 lockfile 同级的项目资产所以做离线文档真正目的是给项目做一个文档锁版本机制。前端项目有 package-lock.json/yarn.lock 锁住依赖版本构建产物可以被版本管理追踪那为什么文档不能锁Ant Design 4.1.5 是一个发行版 tag官方源码库里面保留着与该版本完全对应的文档 markdown。用这份源码构建出的静态站点就是此版本官方文档的完整快照。以后任何人接手这个项目打开内网文档看到的内容和当初用 4.1.5 开发时看到的 API 完全一致。这对排查历史问题、新人上手老项目、多人协作统一认知价值都很大。2. 离线版本文档的常见方案与选型对比动手之前我把能想到的方案都盘了一遍各有适用场景这里直接给大家一个横向对比方案优点缺点适用场景浏览器手动保存网页零成本、上手快SPA 页面保存后大量脚本失效样式错乱只能一页页存容易漏只看一两个组件参数临时应急离线抓站工具整站镜像全自动、覆盖页面多抓下来的 SPA 应用仍依赖运行时脚本目录层级和路由刷新容易出问题搜索功能基本报废快速存档不追求长期维护和版本对应官方源码构建静态站点内容与版本严格对应、结构完整、可定制、可持续维护需要一次性的环境配置和构建操作团队长期使用、内网部署、多版本归档Wiki 或内部知识库摘录可以夹带团队私有经验覆盖不完整、更新滞后、维护者一旦离开就断更团队经验沉淀不能替代官方文档我当时直接排除了前两种。手动保存的效率太低抓站工具对 React 单页应用的支持很不可靠——Ant Design 官网文档本质上是一个 React SPA大量页面内容是运行时异步渲染出来的抓下来只是一堆空壳 HTML点开侧边栏目录都是僵的。官方源码构建是唯一能从根上保证文档内容和 4.1.5 这个版本完全一致的方案。Ant Design 官方仓库的 docs 和 components 目录下就是每个页面对应的 markdown站点构建工具会把这些 markdown 渲染成静态页面。这不光是能用更是可溯源。所以下面的实操部分我会以这个方案为主线。3. 实操全流程从官方源码构建一份可部署的离线文档完整操作可以分为准备环境、拉取源码、修改配置、构建部署四步。我尽量把每一步为什么这么做也讲清楚免得大家抄完命令后遇到问题不知道怎么变通。3.1 准备构建环境构建 Ant Design 4.1.5 的文档站点需要一个能安装依赖并执行构建脚本的机器。考虑到最终产物是纯静态文件初期可以在自己的开发机上完成构建再把产物拷到内网服务器。Node.js 版本是第一个坑点。4.1.5 发布于 2020 年前后它的构建链Webpack 4 那一套在当时的 Node 10/12 上跑得很顺畅但现在很多开发机已经装到了 Node 18 甚至 20。直接用新版 Node 构建老项目十有八九会在编译阶段抛异常。后面我会专门讲这个问题怎么处理这里先建议准备 nvm方便随时切换 Node 版本。3.2 拉取源码并切换到 4.1.5 标签源码直接克隆官方仓库然后切到对应版本。这里的关键点是必须用发行版的 tag 而不是用 master 分支否则你又回到了文档漂移的老路上。git clone --depth 1 --branch 4.1.5 https://github.com/ant-design/ant-design.git cd ant-design克隆完先确认版本git describe --tags输出4.1.5就没问题。然后是安装依赖官方仓库用的是 yarn建议保持与项目一致包管理器混用容易出现 lockfile 冲突yarn install依赖装上之后可以看一眼 package.json 里的 scripts确认一下站点构建命令。4.x 时期的 antd 仓库里站点构建相关的脚本一般形如site:build或docs:build如果你的环境和我的描述不完全一样以你本地 package.json 的实际脚本为准先cat package.json搜一下 site 关键字再执行对应的命令这里不推荐闭眼抄命令。3.3 修改配置文件解决资源路径与部署位置问题构建文档站点最容易踩的隐藏坑之一是资源路径。React SPA 构建出来的 HTML 里js/css 资源默认可能使用绝对路径引用。内网部署时如果服务器路径和构建时配置的路径不一致就会出现首页打开了但样式全丢、点击菜单刷出白屏的现象。所以构建之前去 site 目录或者仓库根目录下的站点配置目录里找 webpack 配置或站点配置文件重点看两个字段站点 URL 或 host 配置改成你内网服务器的实际访问地址资源 publicPath建议改成相对路径./或你部署的子目录路径例如/docs/4.1.5/我当时是直接改成了相对路径这样整个_site构建产物不管扔到内网哪个目录都能直接跑环境迁移成本很低。当然如果用相对路径后部分懒加载 chunk 找不到可以退回绝对子路径方案用 Nginx 的 location 精确控制访问。3.4 构建静态站点并把产物部署到内网执行构建脚本yarn site:build这个过程通常会持续几分钟期间会做 markdown 编译、less 转 css、组件源码打包、国际化文件处理等一堆事情。构建完成后在输出目录比如_site下会生成一组纯静态 HTML/CSS/JS 文件。把这整个目录完整拷贝到内网服务器上用任意静态文件服务托管即可。如果是 Nginx配置大概长这样server { listen 8080; server_name localhost; location / { root /data/antd-docs; index index.html; # 这是解决 SPA 路由刷新 404 的关键 try_files $uri $uri/ /index.html; } }浏览器打开http://内网服务器IP:8080正常情况下就能看到完整的 4.1.5 文档站了。到这里一个能用的离线文档已经完成。但别高兴太早下面这几个坑我在构建过程中踩得非常酸爽提前列出来能帮大家省不少时间。4. 构建过程中的高频踩坑与完整排查思路这些坑不是一次性偶发问题我换了三台机器构建每台都重新撞了一轮。写下来相当于给大家一份排雷手册。4.1 Node 版本引发的编译异常不是代码问题是环境问题第一次构建我用的是当时最新版 Node执行yarn site:build跑不到一半就崩报错信息里出现了 OpenSSL 相关的关键字。这是老项目 新 Node 的典型症状Webpack 4 依赖的加密库调用了新版 Node 已经移除或变更的 OpenSSL 接口。排查思路很简单用 nvm 切换 Node 到 12.x 或 14.x重新装依赖、重新构建即可。这里有个操作顺序的细节切换 Node 版本之后最好把node_modules和 lockfile 缓存都清理掉再重装否则旧版本编译产物和新运行时环境混在一起会冒出一些非常奇怪的二次报错。nvm install 14.21.3 nvm use 14.21.3 rm -rf node_modules yarn install yarn site:build构建环境这件事我的建议是直接在项目目录里放一个.nvmrc文件写上推荐版本号团队任何人来构建都先nvm use。这是很小的习惯但能消灭一大类莫名其妙的构建失败。4.2 纯内网环境下依赖安装失败如何把构建产物搬进内网如果你希望完全在内网机器上完成从拉代码到构建的全流程会遇到另一个麻烦内网机器根本没有外网yarn install当然也拉不下来依赖。即便配了公司内部 npm 镜像组件仓库本身的依赖树又深又大任何一环缺包都会让整个构建停摆。务实的做法是外网构建内网部署在有外网的构建机上完成全部构建拿到_site目录再把这堆静态文件拷贝进内网。因为静态文件不依赖构建机上的任何运行时环境拷过去就是一个自包含站点。如果你坚持要在内网做自动化流水线那需要先搭建一套内网 npm 私服把构建所需的依赖全部同步进去。这个工程量不小但如果团队以后要经常构建其他开源项目的离线文档一次性投入还是值得的。个人建议初期别折腾私服先把手头这个文档跑起来再说。4.3 SPA 路由刷新 404部署阶段的第一大杀手构建产物部署到内网后首页通常能正常打开但只要你在浏览器里按一下 F5 刷新比如当前停留的地址是/components/button/页面大概率直接 404。这不是文档坏了而是 React Router 的 history 模式和静态服务器之间没有配合好前端路由是浏览器端用 History API 模拟的服务器上并不存在/components/button/这个真实目录。排查时可以先在浏览器地址栏手动访问根路径能开说明构建产物没问题问题就出在服务器回退策略。解决办法就是我在 Nginx 配置里写的那行try_files把所有请求都兜底到index.html由前端路由自己决定渲染哪个页面。Haproxy、Caddy、IIS 也都有对应的 fallback 配置处理思路完全相同。如果你的内网环境不允许碰 Nginx 配置还有一条退路把文档路由模式改成 hash 路由访问地址会变成/#/components/button/的样子这种模式下刷新不依赖服务器配置。我个人还是倾向 Nginx 方案URL 更干净也更贴近线上真实使用体验。4.4 搜索功能失效Algolia 搜索在离线环境下的处理Ant Design 在线文档的搜索框非常依赖 Algolia DocSearch 服务构建成离线版本后搜索请求发不出去搜索框要么一直在转圈要么直接报错。我第一次部署完就撞上了这个问题。排查下来搜索组件在构建时会读取一份配置里面包含站点的apiKey、indexName之类的信息纯离线环境下无法访问 Algolia 的接口。我的处理方式是把站点配置里 DocSearch 相关的初始化逻辑去掉或者把搜索框直接替换成一个轻量提示告诉使用者用浏览器内置查找功能CtrlF。对于一份以查 API 为目的的离线文档来说这个功能损失是可以接受的。如果你确实需要站内搜索可以额外部署一个 Meilisearch 或者 TinySearch 之类的内网搜索服务把构建出的文档内容索引进去再把搜索框的接口地址指向内网服务。这是一个更大的工程非必要建议先忍一忍。4.5 字体、图标与第三方 CDN 外链构建产物里的隐形外网依赖就算构建全部成功页面里仍可能残留一部分外链资源比较常见的是 Google Fonts、jsDelivr 等 CDN 上的字体和图标文件。内网打开页面时这些请求会长时间挂起轻则白屏几秒重则阻塞渲染特别是字体文件体积不小网络不通的情况下整个页面看起来就像卡死了。排查方法打开构建产物的 HTML 文件全局搜索http关键字把外链地址一个个揪出来。处理上字体文件可以从对应 CDN 下载后放进本地静态目录改动构建配置里的资源引用路径如果只是个别装饰性资源直接删掉引用即可不影响文档主体功能。实测做完这步完全离线可用才有真正的说服力而不是表面页面出现了、资源全在转圈。5. 离线文档落地之后团队怎么用好这份资产文档部署成功只是开始真正有价值的是让它融入团队的日常开发流程。这里分享几个我在团队内部落地后的经验。5.1 按版本归档形成文档版本矩阵我建议不要只构建一个 4.1.5而是把团队历史项目涉及的关键版本都构建出来按目录归档/data/antd-docs/ ├── 4.1.5/ ├── 4.24.0/ └── 5.0.0/Nginx 对不同版本分别建 location或者直接用一个索引页列出版本清单。这样无论是接手老项目还是评估升级方案都能对比不同版本 API 差异比一个一个去 GitHub 翻 changelog 高效得多。后续依赖升级时补一条构建任务把对应版本的文档同步生成出来就行。5.2 在文档站旁边补充团队私有经验页官方文档解决的是某 API 怎么用的问题但解决不了我们项目里这个 API 这样用会踩坑的问题。我把团队内网上踩过的和 Ant Design 相关的坑整理成 markdown 文件和官方文档放在同一个站点目录下做成一个团队踩坑记录入口。新同学入职先看官方文档再刷一遍内部踩坑记录能少走很多弯路。技术上实现也简单就是往静态站点里多放几个 HTML 页面或者如果用的是支持 markdown 渲染的工具直接在构建流程里把 docs 目录指向两份数据源合并后的目录即可。重要的是建立文档和代码共同维护的团队共识而不是把离线文档部署完就当甩手掌柜。5.3 自动化更新与内网可观测最后给一个可选的进阶优化。如果团队有 CI 系统可以把文档构建做成一条流水线版本 tag 变化时自动触发构建构建完自动推送到内网服务器。即使没有 CI也可以写一个简单的定时任务脚本定期检查仓库新版本提醒负责的同学决定是否纳入归档。这样做的价值在于文档永远和团队实际使用的依赖保持同步不会再出现项目升级了某个小版本、文档还挂着一年前的旧内容的尴尬。加上我前面说的.nvmrc固定环境、构建产物检查外部链接这两步整套离线文档体系的维护成本会降到非常低的水平。我在实际使用中的一个体会是花半小时把这套离线文档建好长期看省的绝不只是等网页加载的那几秒钟。它让团队对组件库的使用有了一致的认知基准查问题、做复盘、带新人都能指着同一份材料说话这种确定性在工程协作里非常值钱。如果你也在为内网环境下的文档查询烦恼强烈建议按这个思路试一次一次构建长期收益。本文还有配套的精品资源点击获取