企业官网建设流程全解析

上周有位同学在群里甩了一张截图，控制台红了一片，组件库文档首页只渲染出半截侧边栏，搜索框点了没反应，右侧的示例代码块也全是空白。他没说是哪个站，但一看侧边栏的排版和示例卡片的样式，我就知道是 Antd 的文档站。这个场景太熟悉了：搜"Antd 官网镜像地址"这几个字的人，九成不是真的想要一串网址，而是想要一个打得开、内容全、版本还跟项目对得上的文档入口。

先把话说在前头：直接给你几个第三方文档地址意义不大，这类站点随时会挂、会停在旧版本、会缺示例。真正靠得住的做法，是在自己可控的地方留一份完整的文档副本，再配一套稳定的包源和静态资源配置。这篇内容就是把这套东西从头拆一遍——文档站怎么在本地跑起来、构建产物怎么托管、包源和静态资源怎么配、版本对不上时怎么排查、团队内怎么长期维护。前端新人能照着抄，内网团队和需要做离线文档的同学也能直接拿去用。

1. 文档打不开时，先分清是网络链路还是资源链路的问题

很多人一遇到文档白屏就下意识认为是"网不行"，然后开始到处找别的入口。实测下来，十次里有六七次根本不是整站不通，而是某几个外链资源加载失败导致的连锁反应。所以第一步不是换地址，是看清楚到底是哪一层断了。

1.1 一次页面加载要经过的三段链路

打开一个组件库文档站，浏览器实际要完成三段互相独立的请求：

• HTML 文档本体：这是唯一"整站能不能进"的判定依据。它拿不到，页面就是纯白或者直接报错。
• 静态资源：打包后的 JS、CSS 文件，通常带哈希文件名。它们挂掉的表现是页面骨架在、样式或交互没了。
• 第三方外链：示例代码里嵌入的图标字体脚本、外部图片、统计脚本。这一类最容易出问题，而且失败时页面往往"看起来正常一半"。

我见过最典型的情况是：HTML 和 JS 都拿到了，侧边栏能点、路由能跳，但示例区一片空白。打开 Network 面板筛一下失败请求，全是某个外链的 iconfont 脚本在超时。这种就不是"站点进不去"，而是"站点依赖的一个外部文件进不去"。两者的处理方式完全不同——前者要换入口或本地部署，后者只要把那一个文件本地化就行。

1.2 用控制台三分钟定位断点

我的习惯动作是固定的三步，顺序不要乱：

1. 打开 DevTools 的 Network 面板，勾上 Disable cache，硬刷新一次。
2. 按状态排序，先看有没有(failed)或者net::ERR_开头的条目，记下它们的域名。
3. 再看 Console，找第一条红色报错而不是最上面那条——最上面那条经常只是被后续错误带出来的。

判断规则很简单：如果失败域名和页面主域名一致，说明是站点自身资源没取到，走本地部署那条路；如果失败域名是别的域，那就是外链问题，把那几个文件下下来放自己的静态目录即可。

还有一种情况值得单独提：页面能打开，但搜索框搜不出东西。组件库文档的搜索通常是构建时生成的索引文件（一个 JSON），点搜索时才异步拉取。这个文件如果 404，表现就是输入关键词后永远转圈或者直接空列表。这个坑很隐蔽，因为页面本身的浏览完全正常，大家会误以为是搜索功能坏了。

提示：排查时不要一上来就清缓存、换浏览器、换设备三件套。先看 Network 的失败列表，比什么都快。

2. 把文档站搬到本地：从拉源码到静态托管的完整路径

确认是站点自身的问题之后，最省心的方案是自己构建一份。这件事比听起来简单，因为组件库的文档站本身就是仓库里的一部分，构建脚本是现成的。

2.1 构建前的三个前置条件

动手之前先确认环境，不然会在莫名其妙的地方卡住：

第三条很多人不当回事。组件库仓库的依赖体量不小，加上构建产物和缓存，两三个 G 很常见。我之前在一台小容量云主机上折腾，装依赖装到 87% 报磁盘满，前面二十分钟全白费。

Node 版本这块有个实操技巧：仓库根目录如果带.nvmrc或.node-version，直接照着装，别自己挑"最新版"。构建工具链对 Node 大版本相当敏感，差一个大版本就可能出现构建产物正常但运行时白屏的情况。

2.2 构建命令与产物结构

流程本身是标准的四步：

git clone <仓库地址> antd-docs-source cd antd-docs-source npm ci npm run build

npm ci比npm install更合适，它严格按 lock 文件安装，不会偷偷升级次版本，构建结果可复现。第一次跑如果卡在某个包上，先看是不是源地址的问题，下一节会细说。

构建脚本的名字各版本不一样，别照抄。正确做法是打开package.json，在scripts里找带build、site、docs字样的那几条，一般会看到类似build:site、docs:build这样的命名。文档站和组件库本体通常是两套构建，选错了会得到一个只有组件产物、没有文档页面的 dist。

构建成功后的产物一般落在dist或site/dist目录，结构大致是：

dist/ ├── index.html ├── umi.[hash].js ├── umi.[hash].css ├── ~dumi-theme-[hash].js └── assets/ └── 若干图片与字体文件

这里有个关键点：产物路径是相对还是绝对。默认配置通常按根路径/生成绝对路径引用。如果你打算把它挂在https://内网域名/antd/这样的子路径下，直接扔上去会全部 404。解决办法是用环境变量或配置项指定基础路径，不同构建工具写法不一样，常见的是BASE_PATH、PUBLIC_PATH这类环境变量，或者配置文件里的base、publicPath字段。我的建议是能挂根路径就挂根路径，用一个独立子域名，别跟子路径较劲，能省掉一堆路由改写。

2.3 用 Nginx 托管并处理路由刷新

产物是纯静态的，任何静态服务器都能托管。Nginx 的配置我一般这么写：

server { listen 80; server_name docs.example.internal; root /var/www/antd-docs; index index.html; location / { try_files $uri $uri/ /index.html; } location ~* \.(js|css|woff2?|ttf|svg|png|jpg)$ { expires 30d; add_header Cache-Control "public, immutable"; } location = /index.html { expires -1; add_header Cache-Control "no-cache"; } }

三个地方值得解释：

try_files ... /index.html是必须的。文档站是单页应用，路由由前端接管，用户直接访问/components/button或者在任意页面按 F5，服务器上并不存在这个路径的文件。不加这一行，刷新就是 404，而且这个 404 很容易被误判成"部署失败"。

带哈希的静态资源给长缓存。文件名里已经带了内容哈希，内容一变文件名就变，所以可以放心设 30 天甚至一年。

index.html必须禁缓存。它是入口，一旦被缓存住，后面所有哈希文件名都还是旧的，用户会一直看到老版本，你更新了也白更新。这个坑我踩过不止一次，表现是"我明明发了新版，同事那边还是老样子"。

内网环境还有一个额外考虑：如果构建机器不能直连外部仓库，需要先把源码打包带进去，或者用一台能出网的机器构建好再把dist拷进去。后者更省事，但要注意构建机和目标机器的 Node 版本差异不影响产物——产物是纯静态文件，不受运行时版本影响，这点可以放心。

3. 包源与静态资源的配置细节：让依赖安装不再卡在半路

构建卡住最常见的原因之一是依赖下载慢或失败。这一节讲清楚源配置的优先级关系，以及几个容易被忽略的残留问题。

3.1 源配置的四个层级与覆盖顺序

包源配置不是一个地方，而是层层覆盖的，优先级从高到低大致是：

1. 命令行参数，如npm install --registry=<地址>
2. 项目根目录的.npmrc
3. 用户级配置，即用户目录下的.npmrc
4. 全局配置，即全局 npmrc 文件

实际生效的是最靠上的那一个。这个顺序解释了一个高频困惑："我明明在项目里配了源，怎么还是慢？"——因为 CI 脚本里写死了命令行参数，或者某个 npm 命令带了参数，把项目配置盖掉了。

我一般的做法是：项目根目录放一份.npmrc并提交进仓库，内容形如：

registry=https://registry.example.com/ strict-ssl=true fetch-timeout=120000

把源固定下来，团队里所有人克隆下来就一致，不用口头传达"记得换源"。fetch-timeout设长一点也有用，大包在慢速网络下经常不是失败而是超时。

注意：这里面填的地址要换成你自己实际在用的公共源或公司内部源。内部源的好处是它有本地缓存，第一次拉慢，后面就快了，而且不会因为外部源抖动导致构建失败。

3.2 lock 文件里的地址残留

这是最容易让人抓狂的一个坑。你把源配好了，npm install还是卡在某个包上，速度完全没变。原因在 lock 文件。

lock 文件里每个依赖都有一个resolved字段，记录的是当初装这个包时用的完整下载地址。如果你手上的 lock 文件是在别的源下生成的，那么重新安装时会优先按resolved里的地址去拉，你的新源配置根本不会生效。

排查方法很直接：打开 lock 文件，搜索一下resolved后面跟的域名，如果不是你现在用的源，那就是它。处理方式有两种：一是删掉 lock 重新生成（会带来版本浮动风险）；二是用文本替换把resolved里的域名批量改掉，再执行安装。团队项目我更推荐第二种，版本锁定不破坏。

顺带提一下，package-lock.json、yarn.lock、pnpm-lock.yaml三种格式里都有类似字段，处理思路一致。

3.3 图标与字体资源的本地化

组件库的图标方案在不同大版本里有明显差异，这直接决定了你要不要处理外链资源：

如果你维护的是 4.x 的老项目，页面里用到了自定义图标集，那么通常会有一段类似这样的代码，通过scriptUrl指向外部脚本：

const IconFont = Icon.createFromIconfontCN({ scriptUrl: '/static/iconfont.js', });

把那个 js 文件下载下来，放到项目的public/static/目录，scriptUrl改成相对路径，外链依赖就断了。改动量极小，收益很直接——从此内网、弱网、外部服务抖动都跟你无关。

还有一类资源容易被忘掉：示例代码里的图片和演示用的第三方库。如果文档里某个组件的示例引了外部图片，那个图片挂了示例区就是一片空白。做完整离线包时，用工具把页面里所有跨域请求抓一遍，逐个本地化，比事后一个个排查省事得多。

4. 版本对不上，才是文档使用中最隐蔽的一类问题

文档能打开了，接下来会遇到一个更麻烦的事：照着文档抄的代码，在项目里报错。这时候大多数人会怀疑自己写错了，实际上很可能是文档版本和项目里的组件版本不是一回事。

4.1 版本映射关系先理清楚

组件库的文档站是按大版本分线维护的，不同版本对应不同的源码分支和构建工具。大致关系如下：

这里的关键认知是：文档站是一个跟着源码分支走的产物，不存在"一份文档覆盖所有版本"这回事。你在搜索引擎里点进去的那个页面，大概率是主干版本，而你的项目可能还停在 4.x。照着主干文档写 4.x 的代码，组件属性名对不上是必然的。

判断自己项目版本的方法很简单，看package.json里那个依赖的版本号，或者直接：

npm ls antd --depth=0

拿到版本号之后，再去对应分支的文档里查。如果自己部署了文档站，最省事的做法是一次性构建两到三个大版本的产物，用不同子目录区分，然后在内部导航页上列清楚。团队里新人最容易犯的错就是查错版本，这一招能从源头上避免。

4.2 一次完整的排查链路

说个我实际处理过的例子。有位同学反馈：文档里的某个表单组件示例，复制到项目里，控制台报"未知属性"。他的判断是文档写错了。

我的排查顺序是这样的：

第一步，确认文档版本。打开文档页，翻到页脚或侧边栏底部，通常会有版本标注。有些站点不显眼，可以看浏览器地址栏里的版本路径段。结果是主干版本。

第二步，确认项目版本。执行npm ls拿到实际版本，是上一代大版本。

第三步，对比属性差异。在两个版本的文档里搜同一个组件名，逐项对比属性表。果然那个属性是新版本才引入的，老版本对应的是另一个名字。

第四步，回到源头验证。在项目里本地起一个最小复现，用老版本的属性名写一遍，报错消失。

整个链路里最有价值的是第一步和第二步——先对齐版本，再谈对错。跳过这两步直接去翻源码找原因，就是纯粹浪费时间。养成习惯之后，看到"文档和实际不一致"的反馈，第一反应固定是"两边版本各是多少"。

提示：给团队做内部文档站时，一定要在页面明显位置标出版本号和构建时间。不加这个，半年后没人说得清这份文档是哪一版。

5. 团队文档站的长期维护：增量更新与缓存策略

自己搭一份文档不是一次性工程，版本会更新，组件会增删。维护策略决定了这个东西三个月后是"团队基础设施"还是"没人管的过期副本"。

5.1 更新频率与触发方式

我的经验是把更新拆成两档：

• 小版本跟进：按月或按季度，拉一次对应分支的最新代码，重新构建。适合稳定期的团队。
• 大版本跟进：新大版本发布后的一到两周内必须更上，否则文档和代码脱节，前面说的版本错配问题就会集中爆发。

自动化的话，一个定时任务是够用的：

#!/usr/bin/env bash set -euo pipefail SRC_DIR=/opt/build/antd-docs-source OUT_DIR=/var/www/antd-docs TMP_DIR=/opt/build/output-$(date +%Y%m%d%H%M) cd "$SRC_DIR" git fetch --all --prune git reset --hard origin/main npm ci npm run build # 产物先放临时目录，构建成功再替换，避免构建失败导致旧版本也被清掉 rsync -a --delete "$SRC_DIR/dist/" "$TMP_DIR/" rm -rf "$OUT_DIR".bak mv "$OUT_DIR" "$OUT_DIR".bak mv "$TMP_DIR" "$OUT_DIR" echo "deployed at $(date)"

几个设计意图值得说明。set -euo pipefail是硬要求，任何一步失败就中断，不会出现"构建失败但旧版本被删了"的灾难。先构建到临时目录再原子替换，是为了保证站点在任何时刻都是可用状态。保留一份.bak是为了回滚——构建成功但产物有问题的情况并不罕见，有个上一版能立刻切回去，比现场调试从容得多。

5.2 缓存与失效的实际配置

静态站点的缓存策略前面提了一半，这里补完整的判断依据：

这里最大的坑是"名字固定但内容会变"那一类。除了 HTML 和搜索索引，还有一些站点会生成sitemap.xml、versions.json之类的文件，同样属于这一类。漏掉它们的后果是：主资源都更新了，但版本列表还是旧的，表现就是页面上显示"最新版本 4.2"，实际代码已经是 5.x 了。

验证缓存有没有配对，有个很简单的办法：发版之后，用一个从没访问过的新浏览器（或者开一个全新的无痕窗口，注意不是复用已有的无痕），打开站点，看侧边栏的版本号和构建时间是不是新的。再用刚才访问过的窗口刷新一次，看是不是也是新的。两个都对新，才算配对。

5.3 搜索索引与内容完整性校验

最后补一个容易被忽略的收尾动作：部署后做一次内容完整性检查。我习惯用脚本抓几个关键页面的 HTTP 状态码，加上一个搜索接口的实际请求。

for p in / /components/button /components/form /docs/react/introduce; do code=$(curl -s -o /dev/null -w "%{http_code}" "http://docs.example.internal$p") echo "$p -> $code" done

正常应该全是 200。如果某个组件页返回 200 但内容是空的，说明是前端路由兜底到了index.html，实际那个页面在构建产物里根本不存在——这种情况路由看起来正常，但用户点进去啥也没有。所以除了状态码，还要抽两个页面看看有没有实质内容，比如抓一下页面里是否包含预期的组件名。

搜索索引单独验一次：

curl -s "http://docs.example.internal/search-index.json" | head -c 200

返回空或者 404，说明索引文件没生成或者路径不对。这个文件不生成的原因通常是构建时跳过了搜索插件，或者产物目录被rsync --delete误删了。

这套东西搭起来之后，团队里就没人再问"文档打不开怎么办"了。我个人在实际操作中的体会是，这件事真正的成本不在技术难度，而在于一开始愿不愿意花两个小时把它做成可自动更新的流水线。做成一次，后面半年基本不用管；图省事手动传一次压缩包，三个月后必然变成没人记得怎么更新、也没人敢删的历史遗留。