企业官网建设流程全解析

1. 为什么我要给一个开源项目从零搭双语 Wiki

先交代背景。我手上维护着一个叫 AI Helper 的开源项目，定位是给开发者提供一套轻量的 AI 辅助工具集，包含文本处理、提示词管理、简单的工作流编排这些模块。项目本身代码量不算大，但 issue 和讨论区里反复出现同一类问题：新用户不知道怎么配置、某个函数参数到底填什么、示例跑不通是环境问题还是用法问题。文档散落在 README、代码注释和几个零散的 Markdown 文件里，中文用户和英文用户看到的内容还不一致。

这种状态下，我做了个决定：给项目从零搭一套双语 Wiki。所谓双语，不是简单地把中文机翻成英文丢上去，而是中英两套内容结构对齐、术语统一、互相可跳转，任何一边更新另一边能同步跟进。这件事听起来像个文档工作，实际上它是一套完整的工程实践，涉及静态站点选型、目录结构设计、多语言路由、搜索、部署流水线，以及最容易被忽略的——长期维护机制。

我写这篇东西，是想把整个搭建过程完整复盘一遍。适合谁看？如果你手上有一个开源项目，文档已经开始失控，或者你正准备给项目补一套像样的文档站，那这篇基本可以照着抄。哪怕你只是想给自己的小工具写个说明页，里面的选型思路和避坑经验也能用上。全文我会按“为什么这么设计—核心细节—实操落地—问题排查”的顺序讲，中间穿插我踩过的坑和实测有效的做法。

2. 整体方案设计与选型思路拆解

2.1 先想清楚双语 Wiki 到底要解决什么问题

很多人一上来就纠结用什么框架，我觉得顺序反了。先明确需求，选型是水到渠成的事。我给 AI Helper 的 Wiki 列了这么几条硬需求：

• 中英内容结构必须一致。同一个功能点，中文页面和英文页面要能一一对应，不能中文有五个章节英文只有三个。
• 写作体验要接近纯 Markdown。我不想让贡献者去学一套复杂的模板语法，开源项目靠的是社区贡献，门槛越低越好。
• 支持全文搜索。文档一多，没有搜索等于没有文档。
• 部署要免费且自动化。开源项目没有预算，能白嫖的静态托管优先。
• 后续能扩展。今天双语，明天可能加日文，结构上要留口子。

把这五条摆出来，方案范围其实就收窄了。纯手写 HTML 不现实，重型 CMS 又太重，静态站点生成器（SSG）是最合适的中间地带。

2.2 静态站点生成器怎么选：我的对比过程

我实际对比了三个主流方向，这里把关键维度列成表，方便你直接对照自己的项目。

我最后选了方案A这一类文档型框架。理由很直接：AI Helper 的核心诉求就是文档，不需要花哨的首页动画和复杂交互，文档型框架内置的多语言、侧边栏、搜索、版本管理这些能力，正好命中我的需求。用通用型框架虽然自由，但多语言路由和搜索都要自己搭，属于重复造轮子。

提示：选型时不要被“功能最全”迷惑，要看“默认配置是否覆盖你 80% 的需求”。文档站这类项目，约定优于配置能省下大量时间。

2.3 双语目录结构的设计逻辑

这是整个项目里最值得说道的部分。多语言文档有两种常见组织方式：

第一种是按语言分目录，比如docs/zh/和docs/en/各放一套完整内容。第二种是按内容分目录，语言作为文件后缀，比如guide.zh.md和guide.en.md放在一起。

我选了第一种，原因是它和文档型框架的 i18n 约定天然契合，而且贡献者心智负担小——中文贡献者只进zh目录，英文贡献者只进en目录，互不干扰。第二种方式虽然文件相邻便于对照，但目录里中英文件混在一起，时间一长容易乱。

具体结构大概是这样：

docs/ zh/ index.md guide/ getting-started.md configuration.md api/ text-utils.md en/ index.md guide/ getting-started.md configuration.md api/ text-utils.md

关键在于两边的相对路径必须完全一致。zh/guide/getting-started.md对应的就是en/guide/getting-started.md。这样语言切换时，框架能自动把当前页面映射到另一种语言的同一路径，用户不会跳回首页。这个约束我会写进贡献指南，作为硬性规则。

2.4 术语统一：双语项目最容易翻车的地方

我见过太多双语项目，中文叫“提示词”，英文一会儿叫 prompt 一会儿叫 instruction，读者直接懵。所以在动手写内容之前，我先建了一份术语对照表，放在仓库根目录，作为翻译和写作的唯一标准。

这份表看起来不起眼，但它是双语 Wiki 能长期保持一致的地基。每次新增术语，先补表再写内容，避免后期大规模返工。

3. 核心细节解析与实操要点

3.1 环境准备与项目初始化

动手之前，先把本地环境理清楚。我用的运行时是当前主流的长期支持版本，包管理器选了生态兼容性最好的那个。这里不写死具体版本号，因为版本迭代快，你按官方文档装最新的稳定版就行。

初始化步骤大致是：

1. 在 AI Helper 仓库里新建一个docs-site目录，和源码目录平级，保持文档工程和代码工程分离。
2. 进入目录，用包管理器初始化项目，安装文档框架及其多语言、搜索相关依赖。
3. 创建配置文件，声明站点标题、语言列表、导航结构。
4. 建立docs/zh和docs/en两个内容目录，各放一个index.md作为首页。

这里有个细节值得说：为什么把文档站单独放一个目录，而不是塞进源码里？因为文档的构建依赖和源码的构建依赖往往是两套东西，混在一起会让依赖树变得臃肿，CI 也不好拆分。分开之后，文档可以独立构建、独立部署，源码仓库的贡献者也不会被文档依赖干扰。

3.2 配置文件的关键参数怎么填

配置文件是整个站点的中枢，我挑几个容易填错的参数讲。

语言列表：要同时声明默认语言和所有支持的语言。默认语言决定了根路径/指向哪套内容。我建议把英文设为默认，因为开源项目的国际访客占比通常更高，中文作为第二语言挂在/zh/下。

导航与侧边栏：不要手动维护一份巨大的侧边栏配置，而是让框架根据目录结构自动生成。手动维护的侧边栏在双语场景下是灾难——你改了一边忘了另一边，两边导航就对不上了。自动生成的前提就是前面说的“两边目录结构完全一致”。

搜索：文档型框架一般有官方搜索插件，支持本地索引，不需要外部服务。配置时注意把两种语言都纳入索引范围，否则中文用户搜不到英文内容（反之亦然）。如果你的用户群体确实需要跨语言搜索，可以开启；如果不需要，按语言隔离搜索体验更清爽。

注意：搜索索引是在构建时生成的，内容更新后必须重新构建才会生效。本地开发时热更新可能不刷新索引，测试搜索功能记得跑一次完整构建。

3.3 内容写作规范：让贡献者不跑偏

文档站搭好只是开始，真正决定质量的是内容规范。我给 AI Helper 定了几条写作规则，写进了贡献指南：

• 每个页面开头必须有一句话概述，说明这个页面解决什么问题，方便搜索引擎和用户快速判断。
• 代码示例必须可运行，且中英两版代码完全一致，只有注释语言不同。
• 截图和示意图统一存放在docs/public下，中英共用，避免重复资源。
• 内部链接使用相对路径，不要写死语言前缀，让框架自动处理语言映射。

这几条里，最后一条最容易被忽略。如果你在中文页面里写死了/en/guide/xxx这样的绝对链接，用户从中文页点过去会直接跳到英文页，体验割裂。用相对路径，框架会根据当前语言自动补全前缀。

3.4 版本管理与内容同步机制

开源项目的文档会随版本变化。我的做法是：主分支的文档永远对应最新开发版，发布版本通过标签或分支冻结。文档框架一般支持版本化配置，可以同时展示多个版本的文档，用户在页面顶部切换。

内容同步方面，我不追求“实时同步”，而是采用以中文为主、英文跟进的策略。原因很现实：核心维护者写中文更快，英文翻译依赖社区。具体流程是，中文内容先合并，然后在英文目录建一个占位文件，标注“待翻译”，并开一个对应的 issue 跟踪。这样既保证了结构完整（路径存在，语言切换不报错），又不会因为翻译滞后阻塞中文更新。

4. 实操过程与核心环节实现

4.1 从零到本地跑通：完整命令流程

下面是我实际操作的完整流程，你可以直接照着走。假设你已经装好了运行时和包管理器。

第一步，创建并进入文档工程目录：

mkdir docs-site && cd docs-site

第二步，初始化项目并安装依赖。不同框架的初始化命令不一样，文档型框架通常提供一个交互式脚手架，按提示选择“文档模式”和需要的语言即可。安装完成后，你会得到一个带默认配置的项目骨架。

第三步，调整目录结构，把默认生成的内容目录改造成zh和en双目录：

mkdir -p docs/zh docs/en

第四步，修改配置文件，声明语言和导航。核心是设置默认语言、语言列表，以及让侧边栏从目录自动生成。

第五步，启动本地开发服务器：

npm run docs:dev

浏览器打开本地地址，你应该能看到默认语言的首页。手动访问/zh/路径，确认中文首页也能正常渲染。这一步验证的是多语言路由是否生效。

4.2 语言切换与路由映射的验证方法

多语言最容易出问题的地方就是路由映射。我设计了一个简单的验证清单，每次改完配置都跑一遍：

1. 在中文首页点击语言切换，看是否跳到英文首页，而不是英文的某个子页面。
2. 在中文的深层页面（比如zh/guide/configuration）切换语言，看是否跳到en/guide/configuration，路径层级完全对应。
3. 如果某个英文页面还没翻译，切换过去应该显示占位内容或 404 提示，而不是白屏或报错。

第 3 点特别重要。很多项目在翻译不全的时候，语言切换直接 404，用户以为站点坏了。我的做法是给未翻译页面放一个统一的占位模板，写明“该页面英文版正在翻译中，欢迎贡献”，并附上贡献入口。这样既诚实，又能把访客转化成贡献者。

4.3 搜索功能的接入与调优

搜索是文档站的生命线。我接入的是框架官方搜索插件，配置过程不复杂，但有几个调优点值得说。

索引范围：默认可能只索引默认语言。要在配置里显式声明索引所有语言，否则中文用户搜不到中文内容。

分词问题：中文和英文的分词逻辑不同。英文按空格切词，中文需要专门的分词支持。好在主流文档框架的搜索插件对中文支持已经比较成熟，配置时确认开启了中文分词选项即可。

结果排序：默认按匹配度排序，但文档站里“标题命中”通常比“正文命中”更重要。如果插件支持权重配置，把标题权重调高，用户搜一个功能名，对应的页面会排在前面。

实测下来，搜索配置好之后，用户查配置项、查函数名的效率提升非常明显，issue 里“这个参数怎么用”这类问题少了一大截。

4.4 自动化部署流水线搭建

部署我选的是静态托管平台，和代码仓库打通，推送到主分支自动构建发布。核心是一份 CI 配置文件，大致逻辑是：

# 伪代码示意，具体语法按平台文档调整 steps: - 检出代码 - 安装运行时和依赖 - 执行文档构建命令 - 将构建产物发布到托管平台

这里有几个实操要点：

• 构建命令要区分开发和生产。开发用docs:dev，生产用docs:build，CI 里必须用后者。
• 缓存依赖目录。文档站依赖安装可能比较慢，缓存node_modules能显著缩短构建时间。
• 构建失败要能通知。配置构建失败时发送通知到项目讨论区或邮件，避免文档悄悄挂掉没人知道。

我踩过的一个坑是：本地构建正常，CI 上却失败，最后发现是 CI 环境的运行时版本和本地不一致。解决办法是在 CI 配置里锁定运行时版本，和本地保持一致。

4.5 自定义域名与访问路径处理

如果项目托管在子路径下（比如example.com/ai-helper/），需要在配置里设置基础路径，否则所有静态资源（CSS、JS、图片）都会 404。这个参数叫base或baseUrl，不同框架叫法不同，但作用一样。

设置之后，本地开发时可能反而访问异常，因为本地是根路径。所以我的习惯是：本地开发不设基础路径，生产构建时通过环境变量注入。这样两边都不受影响。

5. 常见问题与排查技巧实录

5.1 双语 Wiki 高频问题速查表

下面这张表是我在实际维护中整理出来的，基本覆盖了 90% 的常见故障。

5.2 我踩过的三个真实坑

第一个坑：目录结构不一致导致语言切换失效。早期我在英文目录少建了一个api子目录，结果中文 API 页面切换语言时直接 404。后来我写了个简单的校验脚本，在 CI 里对比两个语言目录的文件列表，不一致就构建失败。这个脚本不长，但省了无数手动检查。

第二个坑：图片路径写死语言前缀。我在中文页面里写了/zh/images/xxx.png，结果英文页面引用同一张图时路径不对。正确做法是把图片放在公共目录，用相对路径引用，让框架统一处理。

第三个坑：翻译滞后导致内容误导。有一次中文文档更新了配置项说明，英文还是旧的，英文用户按旧文档操作直接报错。从那以后我养成了习惯：中文内容有破坏性变更时，同步更新英文，哪怕只是加一句“此页面内容已过期，请参考中文版”。

5.3 让贡献者愿意写文档的几个小设计

文档站搭得再好，没人写内容也是空的。我做了几件事来降低贡献门槛：

• 在页面底部加“编辑此页”链接，直接跳到对应 Markdown 文件的编辑界面，省去贡献者找文件的时间。
• 提供页面模板，新建文件时复制模板，自动带上概述、章节结构、术语规范提示。
• 在贡献指南里明确“翻译不算低人一等”，把翻译和原创内容同等对待，鼓励双语贡献者。

实测下来，“编辑此页”这个链接带来的贡献转化最明显。用户看到文档里有个错别字，顺手就能改，不用去研究仓库结构。

5.4 内容更新后的回归检查清单

每次合并文档改动，我会跑一遍这个清单，确保没有引入回归：

1. 本地生产构建是否通过。
2. 中英目录结构是否仍然一致。
3. 语言切换在首页和深层页面是否都正常。
4. 搜索能否搜到新加的内容。
5. 内部链接是否都能点通，没有死链。
6. 移动端布局是否正常（文档站移动端访问占比不低）。

这套清单跑下来大概五分钟，但能挡住绝大多数低级错误。我把它写进了 CI，能自动化的部分（构建、死链检查）自动跑，剩下的人工确认。

6. 后续可扩展的方向与个人体会

这套双语 Wiki 跑了大半年，整体是稳的。如果后面要继续扩展，我脑子里有几个方向。一是加第三语言，结构上已经留好了口子，无非是多一个语言目录和一份术语表。二是把 API 文档从手写改成从代码注释自动生成，减少人工维护成本，但前提是代码注释规范要跟上。三是接入文档质量检查工具，自动检测死链、拼写错误和术语不一致。

我个人在实际操作中的体会是，搭文档站这件事，技术难度不高，难的是长期一致性。双语项目尤其如此，两套内容就像两条腿，任何一条落后都会让整体走不稳。所以与其追求一次搭得多完美，不如先把结构约束和同步机制定死，让后续每一次更新都有章可循。工具会过时，框架会换代，但“结构对齐、术语统一、更新有据”这三条原则，换什么工具都成立。

最后再分享一个小技巧：如果你也在维护开源项目，不妨在 README 顶部放一个显眼的文档站入口，并且在每个 issue 的自动回复里附上相关文档链接。文档写得再好，用户找不到也是白搭。入口这件事，怎么强调都不过分。