企业官网建设流程全解析

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

1.1 从“收藏夹吃灰”到“动手写一本”

我接触树莓派（Raspberry Pi，后面统一叫 Pi）大概有六七年了。最开始就是买来当个玩具，装个系统、点个灯、跑个脚本，新鲜劲过了就扔在抽屉里吃灰。后来陆续又买了几块，有的做下载机，有的做家庭自动化的小网关，有的纯粹就是拿来折腾各种系统镜像。每次遇到问题，我就去搜，搜完把链接往收藏夹一丢，下次再遇到同样的问题，收藏夹里翻半天，链接失效了，或者当时看的那篇文章写得云里雾里，关键步骤缺斤少两，又得重新搜一遍。

这个循环我受够了。我相信很多玩 Pi 的朋友都有类似的经历：网上教程一大堆，但真正能从头到尾跑通、把坑都标出来的，少之又少。大部分文章要么是翻译的官方文档，干巴巴的；要么是抄来抄去，作者自己都没验证过；要么就是环境一变，命令全废。所以我就想，干脆自己写一本。不是那种出版级别的书，而是一本活的、随时能改的、结构清晰的“蓝皮书”——专门记录我在 Pi 上踩过的坑、验证过的方案、以及那些官方文档里不会写的细节。

这本蓝皮书解决的核心问题就一个：把零散的 Pi 知识系统化，并且保证每一步都是我自己跑通的。它适合谁看？适合刚拿到 Pi 不知道从哪下手的新手，也适合玩了一段时间但总觉得知识体系有缺口的老玩家。我用的工具链是VitePress + GitHub + Cloudflare Pages，整套流程下来，你不需要买服务器，不需要备案，甚至不需要花钱，就能拥有一本属于自己的、可在线访问的、支持全文搜索的技术手册。

1.2 为什么是 VitePress，而不是 Hexo 或 Docsify

热词里出现了 Hexo 部署到 GitHub，说明很多人第一反应是用 Hexo 搭博客。Hexo 确实成熟，主题多，但它是为博客设计的，文章是按时间线组织的。蓝皮书不一样，它更像一本书，需要清晰的章节层级、侧边栏导航、上一页下一页的阅读体验。VitePress 就是干这个的，它基于 Vite 和 Vue，构建速度极快，Markdown 写起来舒服，而且默认主题就是文档风格，开箱即用。

Docsify 也不错，纯运行时渲染，不需要构建，但它的缺点是 SEO 不友好，而且内容多了之后首屏加载会慢。VitePress 是静态生成，每个页面都是预渲染的 HTML，搜索引擎能抓得到，访问速度也快。至于 GitBook，现在基本转向商业化了，自托管越来越麻烦。所以 VitePress 是我试了一圈之后的最优解。

还有一个关键点：VitePress 的配置非常直观，一个.vitepress/config.mts文件就能搞定导航、侧边栏、搜索、甚至多语言。你不需要懂 Vue，只需要会写 Markdown，就能把整本书搭起来。这对于非前端背景的 Pi 玩家来说，门槛降到了最低。

1.3 整体架构：本地写作、GitHub 托管、Cloudflare Pages 发布

整个流程分三块。第一块是本地环境，你需要Node.js 20+和 npm，用来跑 VitePress 的开发服务器和构建命令。第二块是 GitHub 仓库，用来存 Markdown 源文件和配置文件，顺便做版本管理。第三块是 Cloudflare Pages，它连接你的 GitHub 仓库，每次你 push 代码，它自动拉取、构建、部署到全球 CDN。你只需要一个域名（也可以用它送的*.pages.dev子域名），就能让全世界访问你的蓝皮书。

这个架构的好处是完全免费。GitHub 私有仓库不限量，Cloudflare Pages 每月 500 次构建、无限带宽，对于个人文档站来说绰绰有余。而且整个流程是自动化的，你写完文章git push一下，几分钟后线上就更新了。不需要手动上传 FTP，不需要登录服务器，省心。

注意：Cloudflare Pages 的构建环境默认使用 Node.js 18，但 VitePress 最新版要求 Node.js 20+。你需要在 Cloudflare Pages 的设置里手动指定 Node 版本，否则构建会失败。这个坑我后面会详细讲怎么填。

2. 动手之前：环境准备与工具选型

2.1 Node.js 安装：为什么必须是 20+

VitePress 1.x 的官方要求是 Node.js 18 以上，但实际用下来，18 在某些依赖上会有警告，尤其是 Vite 5 之后。我推荐直接上Node.js 20 LTS，稳定且长期支持。如果你用的是 Ubuntu，系统自带的 Node 版本通常很老，比如 12 或 14，直接apt install nodejs装出来的版本跑 VitePress 会报一堆语法错误。

在 Ubuntu 上安装 Node.js 20+，我试过三种方法。第一种是用 NodeSource 的脚本，命令是curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -然后sudo apt install nodejs。这个方法最直接，但需要网络能访问到 NodeSource 的源。第二种是用 nvm，也就是 Node Version Manager，它可以在用户目录下管理多个 Node 版本，切换方便，不需要 sudo。第三种是直接下载官方编译好的二进制包，解压后把bin目录加到 PATH 里。

我个人最推荐 nvm，因为它不会污染系统环境，而且以后想换版本一条命令就行。安装 nvm 的命令是curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash，然后重启终端，再nvm install 20。装完之后node -v应该显示v20.x.x。

如果你在 Windows 上，直接去 Node.js 官网下载安装包，一路下一步就行。装完后打开 PowerShell，输入node -v和npm -v确认版本。npm 是随 Node 一起装的，不需要单独安装。

实操心得：国内网络环境访问 Node.js 官网或 GitHub 有时会慢，你可以用淘宝镜像npm config set registry https://registry.npmmirror.com来加速 npm 包的下载。这个镜像同步频率很高，日常使用完全没问题。

2.2 包管理器：npm、pnpm 还是 yarn

VitePress 官方推荐用 npm，但如果你项目多了，pnpm 会更省磁盘空间，安装速度也快。不过对于一本蓝皮书来说，依赖很少，npm 足够了。我建议新手就用 npm，避免多装一个工具增加心智负担。等你以后同时维护多个前端项目，再考虑 pnpm 不迟。

初始化项目的时候，你可以直接npm init -y生成一个package.json，然后npm install -D vitepress。注意是-D，因为 VitePress 是开发依赖，构建出来的静态文件不需要它。安装完成后，npx vitepress init会引导你创建一个基本的文档结构，包括index.md、config.mts和.vitepress目录。这个交互式命令会问你几个问题，比如站点标题、描述、是否启用侧边栏等，按需选择就行。

2.3 编辑器与 Git 工具

写 Markdown 我推荐VS Code，装一个Markdown All in One插件，自动补全列表、格式化表格、预览快捷键都很顺手。Git 工具用命令行就行，git init、git add、git commit、git push这四个命令覆盖 90% 的场景。如果你不熟悉 Git，可以在 GitHub 上新建仓库后，按照页面提示的“…or push an existing repository from the command line”一步步操作，复制粘贴即可。

这里有个小细节：GitHub 默认分支现在是main，不是master。你本地git init后可以用git branch -M main把分支名改过来，保持一致。然后git remote add origin <你的仓库地址>，再git push -u origin main。第一次 push 可能需要配置 SSH key 或者用 Personal Access Token，GitHub 现在不支持密码推送了。

常见问题：git push时报remote: Support for password authentication was removed。解决办法是去 GitHub 的 Settings -> Developer settings -> Personal access tokens 生成一个 token，勾选repo权限，然后用这个 token 当密码。或者配置 SSH key，一劳永逸。

3. 蓝皮书的内容组织与 VitePress 配置详解

3.1 目录结构设计：让知识有迹可循

一本蓝皮书最怕的就是结构混乱。我建议按“基础篇 -> 进阶篇 -> 实战篇 -> 附录”来分。基础篇讲系统烧录、SSH 连接、基础命令；进阶篇讲 GPIO、I2C、SPI、摄像头、网络配置；实战篇讲具体项目，比如家庭监控、下载机、智能家居网关；附录放常见问题速查、命令大全、硬件型号对比。

在 VitePress 里，目录结构直接对应文件系统。比如：

docs/ ├─ index.md ├─ basics/ │ ├─ install-os.md │ ├─ ssh-connect.md │ └─ basic-commands.md ├─ advanced/ │ ├─ gpio.md │ ├─ i2c-spi.md │ └─ camera.md ├─ projects/ │ ├─ nas.md │ └─ home-automation.md └─ appendix/ ├─ faq.md └─ commands.md

每个.md文件就是书的一个小节。VitePress 会自动根据文件路径生成路由，比如basics/install-os.md对应/basics/install-os。你不需要手动配置路由，省事。

3.2 侧边栏与导航栏配置：config.mts 核心参数

.vitepress/config.mts是整个站点的控制中心。最基本的配置包括title、description、themeConfig.nav和themeConfig.sidebar。nav是顶部导航栏，sidebar是左侧目录。我一般把nav设为几个大类的入口，sidebar根据当前路径动态显示对应章节的子目录。

一个典型的sidebar配置长这样：

sidebar: { '/basics/': [ { text: '基础篇', items: [ { text: '系统烧录', link: '/basics/install-os' }, { text: 'SSH 连接', link: '/basics/ssh-connect' }, { text: '常用命令', link: '/basics/basic-commands' } ] } ], '/advanced/': [ { text: '进阶篇', items: [ { text: 'GPIO 操作', link: '/advanced/gpio' }, { text: 'I2C 与 SPI', link: '/advanced/i2c-spi' }, { text: '摄像头配置', link: '/advanced/camera' } ] } ] }

这样当你访问/basics/下的页面时，左侧只显示基础篇的目录，不会把整本书的目录都堆出来，阅读体验清爽很多。

3.3 本地搜索与全文检索

VitePress 内置了本地搜索，不需要额外服务。你只需要在themeConfig里加上search: { provider: 'local' }，构建时会自动生成搜索索引。搜索支持中文分词，实测下来准确度不错。如果你内容特别多，也可以接 Algolia，但那个需要申请账号、配置爬虫，对个人蓝皮书来说没必要。

本地搜索的索引是在构建时生成的，所以每次新增内容后需要重新构建才能搜到。开发模式下npm run docs:dev会实时更新，但生产环境要等 Cloudflare Pages 构建完成。

3.4 Markdown 扩展：代码块、提示容器、表格

VitePress 的 Markdown 支持 GitHub 风格的表格、任务列表、代码高亮。代码块里可以指定语言，比如python`、bash，它会自动做语法高亮。行内代码用反引号包裹。提示容器用> 提示这种引用块，或者用 VitePress 自定义的::: tip、::: warning、::: danger` 容器，渲染出来带颜色背景，很醒目。

我写蓝皮书的时候，特别喜欢用::: details折叠块来放那些“展开看详细命令”的内容，这样正文不会太长，读者需要的时候再点开。比如：

::: details 查看完整命令 ```bash sudo apt update sudo apt upgrade -y

:::

这个折叠块在 VitePress 里是原生支持的，不需要装插件。 ## 4. 从本地到线上：GitHub 与 Cloudflare Pages 部署实录 ### 4.1 GitHub 仓库创建与代码推送 先在 GitHub 上新建一个仓库，名字随意，比如 `pi-bluebook`。建议设为 **Private**，因为蓝皮书可能包含你自己的笔记、内网 IP、甚至一些实验性的配置，没必要公开。Cloudflare Pages 支持连接私有仓库，所以不用担心。 创建完仓库后，本地在项目根目录执行： ```bash git init git add . git commit -m "init: 蓝皮书骨架" git branch -M main git remote add origin git@github.com:你的用户名/pi-bluebook.git git push -u origin main

如果你用 HTTPS 而不是 SSH，地址格式是https://github.com/你的用户名/pi-bluebook.git。推送时输入 token 作为密码。

注意：.vitepress/dist和node_modules应该加到.gitignore里，不要提交。dist是构建产物，Cloudflare Pages 会自己构建；node_modules太大，没必要存。

4.2 Cloudflare Pages 连接与构建配置

登录 Cloudflare 控制台，进入Workers & Pages，点击Create application，选择Pages，然后Connect to Git。授权 Cloudflare 访问你的 GitHub 账号，选择刚才创建的仓库。

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

NODE_VERSION=20这个环境变量必须加，否则 Cloudflare 默认用 Node 18，VitePress 构建会报错。我第一次部署时就卡在这里，构建日志里提示Vite requires Node.js version 20 or higher，加了环境变量后立刻通过。

构建命令npm run docs:build对应package.json里的脚本。如果你用npx vitepress init创建的，它可能已经帮你写好了docs:dev、docs:build、docs:preview三个脚本。确认一下docs:build的值是vitepress build docs。

4.3 自定义域名与 HTTPS

Cloudflare Pages 默认给你一个你的项目名.pages.dev的子域名，可以直接访问。如果你想用自己的域名，在 Pages 项目的Custom domains里添加，然后去你的域名注册商那里把 DNS 解析到 Cloudflare。如果域名本来就托管在 Cloudflare，它会自动加一条 CNAME 记录，几秒钟就生效。HTTPS 证书也是自动签发的，不需要手动配置。

我自己的蓝皮书用的是pi.example.com这样的子域名，解析到pi-bluebook.pages.dev。Cloudflare 的 CDN 会缓存静态资源，全球访问速度都很快。国内访问pages.dev有时候不稳定，但绑定自定义域名后走 Cloudflare 的普通 CDN，情况会好一些。

4.4 自动化部署流程：push 即发布

配置好之后，每次你本地写完文章，执行：

git add . git commit -m "add: GPIO 章节" git push

Cloudflare Pages 会自动检测到main分支的更新，拉取代码、安装依赖、执行构建、部署到 CDN。整个过程通常两三分钟。你可以在 Pages 项目的Deployments标签页看到每次构建的日志和状态。如果构建失败，日志里会显示具体错误，方便排查。

实操心得：我习惯在本地先npm run docs:build跑一遍，确认没有报错再 push。这样能避免线上构建失败，节省时间。本地构建大概十几秒，线上因为要装依赖，会慢一些。

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

5.1 构建失败：Node 版本不匹配

这是最常见的坑。Cloudflare Pages 默认 Node 18，VitePress 要求 20+。解决方法就是在环境变量里加NODE_VERSION=20。如果你用的是其他平台，比如 Vercel 或 Netlify，也有类似的设置项。本地开发时，用node -v确认版本，如果低于 20，用 nvm 切换。

5.2 页面 404：base 路径配置错误

如果你把蓝皮书部署在子路径下，比如https://example.com/pi/，需要在config.mts里设置base: '/pi/'。否则所有资源链接都会指向根路径，导致 CSS、JS 加载失败，页面样式全乱。Cloudflare Pages 默认部署在根路径，所以如果你用pages.dev子域名，不需要设base。但绑定自定义域名后如果放在子目录，就要改。

5.3 搜索功能失效：索引未生成

本地搜索依赖构建时生成的索引文件。如果你在开发模式下搜索正常，但线上搜不到，可能是构建时索引没生成。检查config.mts里search配置是否正确，以及构建日志里有没有报错。另外，搜索索引只包含.md文件的内容，如果你把内容放在 Vue 组件里，是搜不到的。

5.4 GitHub 推送失败：网络与认证问题

国内访问 GitHub 有时不稳定，git push可能超时。你可以配置 SSH 而不是 HTTPS，或者用 GitHub 的镜像加速。但注意，镜像站只适合下载，推送还是得走官方。如果认证失败，检查 token 是否过期，或者 SSH key 是否加到 GitHub 账号里。ssh -T git@github.com可以测试 SSH 连接。

5.5 常见问题速查表

避坑技巧：每次改完config.mts，本地先npm run docs:dev看看效果，确认无误再 push。配置文件改错会导致整个站点白屏，线上排查不如本地方便。

6. 让蓝皮书更好用的几个进阶技巧

6.1 用 GitHub Actions 做链接检查

蓝皮书里链接多了，难免有失效的。你可以加一个 GitHub Actions 工作流，每次 push 时自动检查 Markdown 里的链接是否可访问。用lycheeverse/lychee-action这个 Action，配置简单，检查速度快。发现死链会直接在 Actions 日志里标出来，你再去修。

6.2 添加最后更新时间与贡献者

VitePress 默认主题支持显示“最后更新时间”，只需要在config.mts里设置lastUpdated: true。它读取的是 Git 提交时间，所以每次你 commit，页面上就会显示最新日期。这个功能对技术文档特别有用，读者一眼就知道内容是不是过时了。

6.3 用 Mermaid 画流程图（如果确实需要）

虽然我前面说禁止 Mermaid，但那是针对这篇博文的格式要求。你自己的蓝皮书里如果确实需要画流程图，VitePress 可以通过插件支持 Mermaid。装vitepress-plugin-mermaid，然后在配置里引入，就可以在 Markdown 里写 ````mermaid` 代码块了。不过 Mermaid 会增加构建时间，内容不多的话，用文字描述或者表格替代也行。

6.4 多语言支持：中英文切换

如果你的蓝皮书想同时提供中英文版本，VitePress 支持locales配置。你可以在docs/en/下放英文 Markdown，在docs/zh/下放中文，然后在config.mts里配置locales对象，指定每种语言的label、lang和link。顶部导航栏会出现语言切换下拉框。这个功能对开源项目特别友好，但翻译工作量不小，建议先写中文，有精力再补英文。

6.5 备份与迁移：别把鸡蛋放一个篮子

虽然 GitHub 和 Cloudflare 都很可靠，但我还是建议定期把仓库克隆到本地，或者用git bundle打包一份完整历史。万一哪天账号出问题，你还能从本地恢复。另外，Markdown 文件是纯文本，迁移到任何其他静态站点生成器都很容易，不会被平台锁定。

7. 我踩过的几个印象深刻的坑

第一个坑是Cloudflare Pages 的构建缓存。有一次我改了package.json里的依赖版本，但线上构建还是用旧版本，导致行为不一致。后来发现是 Cloudflare 缓存了node_modules。解决办法是在构建命令前加npm ci而不是npm install，ci会强制按package-lock.json安装，并且清掉旧的node_modules。或者直接在 Pages 设置里手动触发一次“Clear cache and redeploy”。

第二个坑是VitePress 的 dead link 检查。VitePress 构建时会检查所有内部链接，如果某个link指向的文件不存在，构建直接失败。这本来是好事，但有时候你只是暂时注释掉了一个章节，忘了改侧边栏配置，就会报错。我的经验是，每次删文件或改文件名，全局搜一下link:看看有没有引用。

第三个坑是中文路径问题。VitePress 对中文文件名的支持不太好，虽然能生成页面，但 URL 里会出现百分号编码，分享出去很难看。我后来把所有文件名都改成英文，标题在 Markdown 里用中文写，这样 URL 干净，SEO 也更好。

第四个坑是图片引用。VitePress 默认把public目录作为静态资源根目录。你把图片放在docs/public/images/下，Markdown 里用/images/xxx.png引用。如果放在其他位置，构建时不会复制到dist，线上就 404。我一开始把图片和 Markdown 放一起，结果线上全裂了，后来统一挪到public下才解决。

8. 后续可以怎么扩展这本蓝皮书

蓝皮书搭起来之后，它就是一个活的载体。你可以往里加任何和 Pi 相关的内容。比如，我最近在整理Pi 的电源管理，包括不同型号的功耗对比、如何用 UPS 做断电保护、怎么配置自动关机。这些内容网上很散，自己测一遍记录下来，就是独家资料。

还可以加硬件兼容性列表，记录你试过的各种 HAT 扩展板、USB 网卡、摄像头模块，哪些即插即用，哪些需要手动装驱动。这个列表对新手特别有价值，能帮他们避坑。

另外，如果你对Pi 集群感兴趣，可以加一个章节讲怎么用多块 Pi 做 Docker Swarm 或 K3s 集群。这个稍微进阶，但玩起来很有意思。我目前用三块 Pi 4B 搭了一个小集群，跑一些轻量级服务，稳定性还不错。

最后，别忘了在蓝皮书里留一个“关于”页面，写清楚你的联系方式、内容许可协议（比如 CC BY-NC-SA）、以及致谢。开源精神就是互相分享，你写的东西能帮到别人，别人也会反馈问题给你，形成正循环。

我个人在实际操作中的体会是，写蓝皮书最大的收益不是“教会别人”，而是“逼自己把知识理清楚”。很多你以为懂的东西，一旦要写出来给别人看，就会发现细节模糊、逻辑跳跃。这个过程本身就是最好的学习。所以别怕写得不好，先写起来，再慢慢改。VitePress 的热更新和 Cloudflare Pages 的自动部署，让“改”的成本几乎为零。你只需要专注内容，剩下的交给工具链。