企业官网建设流程全解析

1. 缘起：为什么要折腾一本自己的 Pi 蓝皮书

1.1 从“信息焦虑”到“知识沉淀”的转变

说实话，我接触 Pi 这个生态已经有很长一段时间了。最开始和大多数人一样，每天泡在各种群里刷消息，看别人转发截图、讨论进度、猜测下一步动作。信息量确实大，但问题是——这些内容散落在聊天记录、短视频、论坛帖子里，过两天想回头查一个具体操作步骤，翻半天找不到。更麻烦的是，很多内容互相矛盾，今天看到一种说法，明天又看到另一种，根本不知道该信哪个。

这种状态持续了大概两三个月，我意识到一个问题：如果没有一个属于自己的知识库，你永远在被动接收别人的二手信息。别人嚼过的东西，要么丢了细节，要么加了主观判断，你拿到的已经不是原味了。于是我开始琢磨，能不能把 Pi 相关的核心知识、操作流程、常见问题，按照自己的理解整理成一本结构化的“蓝皮书”。

这里的“蓝皮书”不是官方出版物，而是一种个人知识管理的产物。它更像是一本持续更新的操作手册，把散落的信息按照逻辑重新编排，方便自己查阅，也方便分享给身边的朋友。你可能会问，为什么不直接写个文档放网盘？原因很简单：网盘链接会失效，文档格式会乱，而且没法做版本管理。我需要的是一个能在线访问、支持搜索、方便更新、还能追溯修改历史的方案。

1.2 为什么选择 VitePress + GitHub + Cloudflare Pages 这套组合

确定了要做在线文档之后，接下来就是选工具。市面上的静态站点生成器不少，Hexo、Hugo、Docusaurus、VitePress 各有各的优缺点。我最终选了 VitePress，理由有这么几条。

第一，上手成本低。VitePress 基于 Vite 和 Vue，如果你稍微接触过前端，基本半天就能跑起来。它的配置文件就是一个简单的 JavaScript 文件，不需要学复杂的模板语法。第二，默认主题够用。VitePress 自带的默认主题已经包含了侧边栏、导航栏、搜索、暗色模式这些文档站必备的功能，不需要额外折腾插件。第三，构建速度快。Vite 的冷启动和热更新速度确实快，本地写文章的时候几乎感觉不到延迟，这对需要频繁预览的写作场景很重要。

至于 GitHub，它承担的是代码托管和版本管理的角色。每次修改都留下记录，万一改错了可以随时回滚。而且 GitHub 的 Release 功能可以用来发布打包好的静态文件，方便做备份。Cloudflare Pages 则是部署和分发环节，它和 GitHub 打通之后，每次推送代码自动触发构建和部署，完全不需要手动上传文件。而且 Cloudflare 的全球节点覆盖不错，访问速度在国内也还能接受。

这套组合的核心逻辑是：本地写作 → Git 推送 → 自动构建 → 全球访问。整个流程跑通之后，你只需要专注于内容本身，剩下的交给工具链。

1.3 适合哪些人参考这套方案

这套方案不是只针对 Pi 蓝皮书，任何需要做个人知识库、项目文档、学习笔记、产品手册的场景都适用。具体来说，如果你符合以下任何一种情况，这篇文章的内容应该对你有帮助：

• 手里有一堆零散笔记，想整理成结构化文档但不知道用什么工具
• 用过在线文档平台，但担心平台倒闭或者收费政策变化
• 想学 Git 和自动化部署，但觉得门槛太高一直没动手
• 已经在用 VitePress 或类似工具，但部署环节总是出问题
• 对 Pi 生态感兴趣，想自己整理一份参考资料

我接下来的内容会按照环境准备、项目搭建、内容组织、部署上线、问题排查这个顺序展开，每一步都会说明为什么这么做，以及我踩过哪些坑。你可以跟着一步步操作，也可以只挑自己需要的部分看。

2. 环境准备：Node.js 安装与基础工具链配置

2.1 Node.js 版本选择与安装方式对比

VitePress 对 Node.js 版本有要求，官方建议Node.js 18 或更高版本。我实测下来，Node.js 20 LTS 是最稳的选择，兼容性和性能都比较平衡。如果你用的是 Ubuntu 系统，安装方式主要有三种，我分别说一下各自的优缺点。

第一种是通过 NodeSource 仓库安装。这是最推荐的方式，因为版本管理清晰，升级方便。具体命令是先用 curl 拉取 NodeSource 的安装脚本，然后通过 apt 安装。这种方式的优点是系统级安装，所有用户都能用，缺点是切换版本需要卸载重装。

第二种是通过 nvm 安装。nvm 是 Node Version Manager，适合需要在多个 Node.js 版本之间切换的场景。安装 nvm 之后，可以用nvm install 20安装指定版本，用nvm use 20切换。优点是灵活，缺点是每次新开终端需要确认默认版本。

第三种是直接下载二进制包。从 Node.js 官网下载对应系统的压缩包，解压后配置环境变量。这种方式适合没有 root 权限的环境，但手动管理路径比较麻烦。

我个人的建议是：如果你是 Ubuntu 桌面用户，用 NodeSource 仓库安装；如果你需要同时维护多个项目，用 nvm。下面给出 NodeSource 方式的完整命令，你可以直接复制执行。

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs

安装完成后，用node -v和npm -v验证版本。如果输出类似v20.x.x和10.x.x，说明安装成功。

注意：如果你在国内网络环境下执行上述命令遇到超时，可以尝试更换 npm 的镜像源。执行npm config set registry https://registry.npmmirror.com可以加速后续的包安装过程。

2.2 Git 配置与 GitHub 账号准备

Git 是版本控制工具，GitHub 是代码托管平台，两者配合使用。Ubuntu 上安装 Git 很简单，一条命令搞定：

sudo apt-get install -y git

安装之后需要做基础配置，主要是用户名和邮箱。这两个信息会出现在每次提交记录里，所以建议用你 GitHub 账号关联的邮箱。

git config --global user.name "你的用户名" git config --global user.email "你的邮箱"

接下来是 GitHub 账号。如果你还没有账号，去官网注册一个就行。注册完成后，建议做两件事：开启双因素认证和配置 SSH 密钥。双因素认证是为了账号安全，SSH 密钥是为了免密码推送代码。

生成 SSH 密钥的命令是ssh-keygen -t ed25519 -C "你的邮箱"，一路回车即可。然后把~/.ssh/id_ed25519.pub文件的内容复制到 GitHub 的 SSH Keys 设置页面。验证是否配置成功可以用ssh -T git@github.com，如果看到欢迎信息就说明通了。

实操心得：GitHub 的网页访问在国内有时不太稳定，如果遇到打不开的情况，可以尝试刷新或者换个时间段。但 Git 的 SSH 推送通常比较稳定，所以建议优先配置 SSH 方式，而不是用 HTTPS。

2.3 包管理器选择：npm、pnpm 还是 yarn

Node.js 自带 npm，但 npm 在安装大量依赖时速度偏慢，而且磁盘占用比较大。pnpm 是近几年比较流行的替代方案，它通过硬链接的方式共享依赖，节省磁盘空间，安装速度也更快。yarn 则是 Facebook 推出的方案，生态成熟但近年热度有所下降。

我现在的习惯是用 pnpm 管理 VitePress 项目。安装 pnpm 的命令是npm install -g pnpm，安装完成后用pnpm -v验证。后续所有涉及安装依赖的操作，你都可以把npm install替换成pnpm install，速度会明显提升。

当然，如果你不想额外装工具，直接用 npm 也完全没问题。VitePress 官方文档的示例命令都是基于 npm 的，兼容性最好。选择哪个取决于你对速度和磁盘占用的敏感程度。

3. 项目搭建：从零初始化 VitePress 文档站

3.1 创建项目目录与初始化 package.json

找一个你习惯存放代码的目录，比如~/projects，然后创建一个新文件夹：

mkdir pi-bluebook && cd pi-bluebook

接下来初始化 package.json。如果你用 npm，执行npm init -y；如果用 pnpm，执行pnpm init。这个文件记录了项目的依赖信息和脚本命令，是 Node.js 项目的核心配置文件。

初始化完成后，安装 VitePress 作为开发依赖：

pnpm add -D vitepress

或者用 npm：

npm install -D vitepress

安装完成后，你会在node_modules目录下看到 vitepress 相关的包。这时候可以运行npx vitepress init来启动初始化向导。向导会问你几个问题：文档放在哪个目录、站点标题是什么、描述是什么、是否使用默认主题。对于新手，我建议全部选默认选项，后面可以随时改。

3.2 目录结构设计与文件组织逻辑

VitePress 初始化完成后，典型的目录结构是这样的：

pi-bluebook/ ├── docs/ │ ├── .vitepress/ │ │ └── config.mjs │ ├── index.md │ └── public/ ├── package.json └── node_modules/

docs目录是文档的根目录，所有 Markdown 文件都放在这里。.vitepress目录存放配置文件和构建缓存，config.mjs是核心配置文件。public目录用于存放静态资源，比如图片、图标、robots.txt 等。

我建议在docs下再按主题建子目录，比如docs/guide/放入门指南，docs/advanced/放进阶内容，docs/faq/放常见问题。这样结构清晰，后续维护也方便。每个子目录下可以有一个index.md作为该章节的入口页面。

注意事项：VitePress 默认会把docs作为站点根目录，所以访问路径是相对于docs的。比如docs/guide/index.md对应的 URL 是/guide/。这一点在配置侧边栏和导航栏的时候要特别注意。

3.3 核心配置文件 config.mjs 详解

config.mjs是整个站点的控制中心，我挑几个最常用的配置项说明一下。

import { defineConfig } from 'vitepress' export default defineConfig({ title: "Pi 蓝皮书", description: "从零开始整理 Pi 生态的核心知识", lang: 'zh-CN', base: '/', themeConfig: { nav: [ { text: '首页', link: '/' }, { text: '指南', link: '/guide/' }, { text: '常见问题', link: '/faq/' } ], sidebar: { '/guide/': [ { text: '入门', items: [ { text: '环境准备', link: '/guide/setup' }, { text: '基础概念', link: '/guide/concepts' } ] } ] }, socialLinks: [ { icon: 'github', link: 'https://github.com/你的用户名/pi-bluebook' } ], search: { provider: 'local' } } })

title和description会出现在浏览器标签页和搜索引擎结果里。base是部署路径，如果你部署在子目录下需要修改，部署在根目录就保持/。nav是顶部导航栏，sidebar是侧边栏，两者配合使用可以构建清晰的导航体系。search开启本地搜索后，VitePress 会自动为你的文档建立搜索索引，不需要额外配置。

实操心得：base这个配置项很容易踩坑。如果你部署到 Cloudflare Pages，默认是根域名，base保持/就行。但如果部署到 GitHub Pages 的项目页面，路径会变成/项目名/，这时候base必须改成/项目名/，否则所有资源都会 404。

4. 内容组织：Markdown 写作规范与进阶技巧

4.1 Markdown 基础语法与 VitePress 扩展

Markdown 是写文档的核心格式，基础语法包括标题、列表、链接、图片、代码块、引用等。这些内容网上教程很多，我就不重复了。重点说一下 VitePress 对 Markdown 的扩展能力，这些是普通 Markdown 编辑器没有的。

第一个是自定义容器。VitePress 支持tip、warning、danger、info等类型的容器，语法是在引用块前加类型标记：

::: tip 提示 这是一个提示信息 ::: ::: warning 注意 这是一个警告信息 :::

渲染出来会带有不同的颜色和图标，视觉上比普通引用块更醒目。第二个是代码块行高亮。你可以在代码块的语言标记后面加上{1,3-5}来高亮特定行，方便读者定位关键代码。第三个是代码组。用::: code-group包裹多个代码块，可以渲染成带标签页的切换效果，适合展示不同包管理器的命令。

这些扩展语法在写技术文档时特别实用，能让内容层次更清晰，读者体验也更好。

4.2 侧边栏与导航栏的配置策略

侧边栏和导航栏是文档站的门面，配置得好不好直接影响读者的浏览体验。我的经验是：导航栏放一级分类，侧边栏放当前分类下的所有页面。

导航栏不要放太多项，一般控制在 5 个以内。比如“首页、指南、进阶、常见问题、关于”这样的结构就够用了。侧边栏则要根据内容量灵活调整，如果某个分类下页面超过 10 个，建议再分子组，用collapsed: false控制默认展开状态。

还有一个技巧是动态侧边栏。如果你的文档结构比较规整，可以用代码自动生成侧边栏配置，而不是手动一个个写。VitePress 支持在config.mjs里引入 Node.js 模块，你可以写一个函数扫描docs目录，根据文件结构生成 sidebar 数组。这样新增页面时不需要改配置，维护成本大大降低。

4.3 图片、附件与静态资源管理

文档里的图片和附件统一放在docs/public目录下。引用的时候用绝对路径，比如![示意图](/images/pi-flow.png)。这样不管当前页面在哪个层级，路径都不会出错。

图片建议做两件事：压缩和命名规范。压缩可以用 TinyPNG 或者 squoosh 这类在线工具，把 PNG 转成 WebP 格式能显著减小体积。命名规范建议用英文小写加连字符，比如pi-wallet-setup.png，避免用中文或空格，防止在某些环境下出现编码问题。

如果附件比较大，比如 PDF 或者压缩包，建议放到 GitHub Release 里，然后在文档中放下载链接。这样不会拖慢站点构建速度，也方便做版本管理。

注意事项：public目录下的文件不会被 VitePress 处理，会原样复制到构建输出目录。所以不要在这里放需要编译的源文件，只放最终产物。

5. 部署上线：GitHub 与 Cloudflare Pages 联动

5.1 创建 GitHub 仓库与首次推送

在 GitHub 上新建一个仓库，名字就叫pi-bluebook，描述可以写“Pi 生态知识库”。创建时不要勾选初始化 README，因为我们要推送本地已有的项目。

回到本地项目目录，执行以下命令：

git init git add . git commit -m "初始化 VitePress 项目" git branch -M main git remote add origin git@github.com:你的用户名/pi-bluebook.git git push -u origin main

推送成功后，刷新 GitHub 页面就能看到你的代码了。如果推送时报错提示权限问题，检查一下 SSH 密钥是否配置正确。

实操心得：.gitignore文件很重要，一定要把node_modules和.vitepress/cache、.vitepress/dist加进去。否则每次提交都会带上几万个依赖文件，仓库体积会爆炸。

5.2 Cloudflare Pages 项目创建与构建配置

登录 Cloudflare 控制台，找到 Pages 服务，点击“创建项目”，选择“连接到 Git”。授权 Cloudflare 访问你的 GitHub 账号后，选中刚才创建的pi-bluebook仓库。

接下来是构建配置，这是最关键的一步：

构建命令需要和package.json里的 scripts 对应。VitePress 初始化时通常会生成docs:dev、docs:build、docs:preview三个脚本，我们用的是docs:build。输出目录固定是docs/.vitepress/dist，这是 VitePress 的默认构建输出路径。

环境变量里加一个NODE_VERSION=20，确保构建环境用的是 Node.js 20。如果项目里用了 pnpm，还需要确保 Cloudflare 的构建环境能识别 pnpm，通常它会自动检测pnpm-lock.yaml文件并安装 pnpm。

5.3 自定义域名与 HTTPS 配置

Cloudflare Pages 默认会分配一个*.pages.dev的域名，可以直接访问。如果你有自己的域名，可以在“自定义域”里添加。添加后按照提示在 DNS 服务商处配置 CNAME 记录，指向 Cloudflare 分配的域名。

HTTPS 是自动开启的，Cloudflare 会为你的域名签发证书，不需要手动配置。如果你对访问速度有更高要求，可以开启 Cloudflare 的缓存优化和 Brotli 压缩，这些在控制台里都是开关式的操作。

注意事项：自定义域名生效需要一些时间，通常几分钟到几小时不等。如果配置后访问不了，先检查 DNS 记录是否正确，再确认 Cloudflare 的 SSL/TLS 模式是否设置为“完全”或“完全（严格）”。

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

6.1 构建失败与依赖安装问题

构建失败最常见的原因是依赖版本不兼容。VitePress 对 Node.js 版本有要求，如果 Cloudflare 构建环境用的是 Node.js 16，就会报错。解决方法是在环境变量里明确指定NODE_VERSION=20。

另一个常见问题是锁文件冲突。如果你本地用 pnpm 生成了pnpm-lock.yaml，但 Cloudflare 尝试用 npm 安装，就会出问题。解决方法是确保仓库里只有一种锁文件，要么全用 pnpm，要么全用 npm。

还有一种情况是内存不足。VitePress 构建大型文档站时可能占用较多内存，如果 Cloudflare 的免费套餐内存限制导致构建失败，可以尝试减少同时构建的页面数量，或者升级套餐。

6.2 页面 404 与资源路径错误

页面 404 通常和base配置有关。如果你部署在子路径下，base必须和实际路径一致。比如部署在https://example.com/docs/，base就要设为/docs/。

资源路径错误表现为图片加载不出来、样式丢失。检查一下config.mjs里的base是否配置正确，以及图片引用是否用了绝对路径。如果图片放在public/images/下，引用应该是/images/xxx.png，而不是./images/xxx.png。

6.3 搜索功能失效与索引问题

VitePress 的本地搜索依赖构建时生成的索引文件。如果搜索没结果，先确认themeConfig.search是否配置了provider: 'local'。然后检查构建输出目录里是否有vp-search-index相关的文件。

如果索引文件存在但搜索仍然无效，可能是浏览器缓存问题，尝试强制刷新或者换个浏览器测试。另外，搜索索引是在构建时生成的，如果你在本地开发模式下测试搜索，需要先执行一次完整构建。

6.4 常见问题速查表

实操心得：遇到构建问题时，第一件事是看构建日志。Cloudflare Pages 的部署日志会详细列出每一步的执行结果和错误信息，大部分问题看日志就能定位。不要盲目改配置，先搞清楚报错原因再动手。

7. 持续维护与内容迭代的一些经验

7.1 版本管理与更新节奏

文档站上线只是开始，后续的维护才是重头戏。我的做法是用 Git 分支管理内容更新。主分支保持稳定，新内容在dev分支上写，写完预览没问题再合并到主分支。这样即使写了一半的内容也不会影响线上版本。

更新节奏上，我建议小步快跑。不要攒一大堆改动一次性推送，而是每完成一个章节或者修复一个错误就提交一次。这样每次构建时间短，出问题也容易定位。

7.2 内容质量的自我检查清单

写技术文档最怕的是自己觉得写清楚了，读者却看不懂。我每次发布前会过一遍这个清单：

• 操作步骤是否完整，有没有跳步
• 命令和配置是否经过实际验证
• 专业术语是否有解释或类比
• 是否有过时的信息需要更新
• 链接是否有效，图片是否正常显示

如果条件允许，找一个不熟悉这个领域的朋友试读一下，看看他能不能跟着操作走通。这比你自己检查十遍都管用。

7.3 后续可以扩展的方向

这套方案跑通之后，你还可以做很多扩展。比如接入评论系统，让读者可以反馈问题；添加版本切换，同时维护多个版本的文档；集成分析工具，了解读者最关注哪些内容；自动化检查，用 GitHub Actions 做链接有效性和拼写检查。

工具是死的，需求是活的。先把核心流程跑通，再根据实际需要逐步添加功能，不要一开始就追求大而全。我见过太多项目因为过度设计而半途而废，反而是那些从简单开始、持续迭代的项目活了下来。

最后分享一个我自己的习惯：每次遇到问题并解决之后，立刻把解决过程记录到文档的“常见问题”章节里。这样下次再遇到同样的问题，直接查自己的文档就行，不用重新搜索。日积月累，这本蓝皮书就变成了你个人经验的结晶，价值远超最初预期。