BYR Docs Blog

主题

站长不日毕业离校，本站未来交予诸位。

返回
指引

从零搭建 BYR Docs 网站

cppHuskycppHusky
发布时间 2026年3月1日

前言 ​

常言道人各有志。BYR Docs 对我来说只是个出于兴趣搭建的服务性站点，在这段时间里，经过一众同学帮助，也算得上小有成绩。

不过我本人很快就要远赴他乡，且有更多自己想做的事情，难以再继续维护 BYR Docs 的运转了。对我来说，BYR Docs 的最佳结局就是有序关停。

但也有不少人受惠于本站，不希望它就此消失。都说授人以鱼不如授人以渔，我想，索性把搭建 BYR Docs 的方法公诸于世，以俟后人重新搭建，岂不更好？

于是我写了这篇文章，并将在未来 BYR Docs 关停之前无条件把全部资料分享到 GitHub/BYRBT 中。余下的事，就留待后人完成了。

BYR Docs 概况 ​

目前 BYR Docs 的项目主要包括以下部分：

  • BYR Docs 主站是我们的主阵地，提供电子书、考试题目和其它资料的直接下载。主站布署于 Cloudflare Worker 中，其文件全部存储于 Cloudflare R2 对象存储服务器中，而可供检索的元信息保存于 GitHub 仓库中。
    • BYR Docs Publish附属于主站，实现上传功能。它为一般用户提供更好的文件上传及元信息填写、提交服务。Publish 布署于 Cloudflare Worker 中。
  • 维基真题是主站试题部分的延伸，提供可编辑的试题库，允许用户以更零散的方式贡献试题和答案。维基真题布署于 Cloudflare Page 中。
  • BUPT 生存指南是另一个独立项目，提供北京邮电大学两校区的生活学习指南，以帮助新生更好地适应学校环境。生存指南布署于 Cloudflare Page 中。

BYR Docs 的几个项目之间都是较为独立的，不存在很强的依赖关系。比如说，你可以只fork BUPT 生存指南的仓库，做成一个单独的生存指南网站；你也可以只使用维基真题的源代码，做一个单独的维基网站；当然，只搭建主站而抛弃维基也是完全可行的，只不过会缺少一部分来自维基的题目；只搭建主站而不搭建 Publish 也没关系，只是文件上传和元信息录入会有些麻烦。

不过，Publish 必须配合主站搭建，否则便没有意义。

以下我将分别介绍各个子项目的数据获取/搭建方案。

BYR Docs 主站 ​

所需资料 ​

BYR Docs 需要的资料包括文件和元信息两部分。byrdocs-archive 仓库中提供了关于文件和元信息的简单规则，供你参考。

BYR Docs 的文件统一存储于 Cloudflare R2 Object Storage 中，分为可公开的数据和非公开的资源文件两部分。

站点元信息来源于 byrdocs-archive 仓库，以可读性较强的 YAML 格式保存。它定义了一些自动化流程，可以使用 byrdocs-check 仓库 中的程序完成格式检查、数据更新等工作。

BYR Docs 的网站代码位于 byrdocs 仓库 中。

你需要准备的资料包括：

  • 下载好全部资源文件，你可以在BYRBT中下载种子ID为362294的文件并解压得到；
  • 一个 byrdocs-archive 仓库；
  • 一个 byrdocs 仓库；
  • （可选）如果有需要，增加一个 byrdocs-check 仓库，以使其符合你的需求。关于 byrdocs-check 的介绍不在本文内容之列。

所需环境 ​

  • 如果你需要同时启用 BYR Docs Publish，强烈建议你注册一个 GitHub Organization，并把以上仓库移入该组织名下。
  • 你需要拥有一个 Cloudflare 账号。
  • 你的本地开发环境需要安装 Node.js 及 pnpm。
  • 本项目的最佳布署方法是使用 Wrangler CLI。它作为 byrdocs 仓库的依赖包，在 准备开发环境 一步中可以安装。
  • 你需要下载 Minio Client 并安装，以便批量向 R2 存储库内写入文件；
  • 如果需要批处理元信息，你需要安装 Python 运行环境。

关于 Cloudflare 资费 ​

目前本人维持 BYR Docs 主站所需的支出约为每月 0.4 USD，支出完全由 R2 产生。

  • 你可以使用 Cloudflare Workers 的免费订阅，或者每月支付 5 USD 使用 Workers 付费订阅。使用免费订阅不影响网站的正常功能，但存在一定的运行和访问量限制。请参考 Limits - Cloudflare Docs 并自行评估是否需要付费。
  • 本站文件存读所使用的 R2 Object Storage 容量和操作数可能超出免费额度的限制，Cloudflare 将对超出部分收费，详见 Pricing - R2。

搭建步骤 ​

因为搭建过程较为繁琐，我将其分为几个子过程，分别加以介绍。

  1. 准备 byrdocs 开发环境
  2. 准备 BYR Docs 文件
  3. 准备 BYR Docs Archive

准备 byrdocs 开发环境 ​

首先，我们需要搭建本地开发环境。

  1. 将 byrdocs 仓库拷贝到本地，并进入该目录。
  2. 下载依赖。
bash
pnpm i
  1. 登录 Wrangler CLI，按照指示完成登录。
bash
npx wrangler login
  1. 配置 D1 数据库。
    1. 打开 wrangler.toml，删除所有的 [[d1_databases]] 表项。
    2. 创建名为 byrdocs 的 D1 数据库。
    bash
    npx wrangler d1 create byrdocs --binding DB
    1. Wrangler 会为你生成一则 Toml 配置，将其复制到 wrangler.toml 中，如：
    toml
    [[d1_databases]]
binding = "DB"
database_name = "byrdocs"
database_id = $DATABASE_ID
    1. 应用 D1 数据库迁移。
    bash
    npx wrangler d1 migrations apply byrdocs --remote
  2. 建立一个可以通过 Prisma 访问并读写 D1 数据库的 Token。在 Account API tokens 页面中点击 Create Token，选择 Create Custom Token。为整个 Account 设置 D1 的读权限和写权限，如下图所示。 Creating D1 Token
  3. 当 Token 建立成功后，注意记录并保存完成页面的 Token value。
  4. 填写环境变量。你需要准备以下两个文件：
    1. .env 定义了构建时用到的环境变量，格式如下，请依实际情况自行更改。
    ini
    # BYR Docs 的域名
BYRDOCS_SITE_URL=https://byrdocs.org
# BYR Docs Publish 的域名
PUBLISH_SITE_URL=https://publish.byrdocs.org
# 你的 byrdocs-archive 对应的 GitHub 仓库
ARCHIVE_REPO_URL=https://github.com/byrdocs/byrdocs-archive
    1. .dev.vars 定义了 Cloudflare 后端用到的环境变量，格式如下，请依实际情况自行更改。
    ini
    # 第6步得到的 D1 读写 Token
CLOUDFLARE_D1_TOKEN=
# 你的 Cloudflare Account Id，可通过命令 `npx wrangler whoami` 查得
CLOUDFLARE_ACCOUNT_ID=
# D1 的数据库 ID，在生成数据库时得到，可在 `wrangler.toml` 中找到
CLOUDFLARE_DATABASE_ID=
# 自行生成一个字母/数字/符号串，且不少于32字符
JWT_SECRET=
# 同上，但不要使用相同的值
BYRDOCS_SITE_TOKEN=
# 主站网址，也是你为主站设定的自定义域名，见下文第12步
BYRDOCS_SITE_URL="https://byrdocs.org"
# byrdocs-data 存储桶的自定义域名，见“准备 BYR Docs 文件”第7步
R2_DATA_SITE_URL="https://files.byrdocs.org"
# BYR Docs Publish 的域名
PUBLISH_SITE_URL="https://publish.byrdocs.org"
# BYR Docs Publish 的测试地址
PUBLISH_DEV_SITE_URL="http://localhost:3000"
# BYR Docs Wiki 的域名
WIKI_SITE_URL="https://wiki.byrdocs.org"
# 测试用的网站域名
DEV_SITE_URL="https://byrdocs.cpphusky.workers.dev"
# 你的 byrdocs-archive 对应的 GitHub 仓库
ARCHIVE_REPO_URL="https://github.com/byrdocs/byrdocs-archive"
  5. 现在运行 pnpm run deploy 进行初次布署。但此时因为尚未准备好所需的信息和文件，所以网站的正常功能还不可用。
  6. 接下来，将 .dev.vars 中的环境变量上传至 Cloudflare Worker 中。
bash
npx wrangler secret bulk .dev.vars
  1. 在 Workers & Pages 列表中，选中自己的 byrdocs 站点。找到 Settings -> Build ，点击 Connect，打开选单。
  2. 选好你的 GitHub 仓库和分支，Build command 填 pnpm run build，Deploy command 填 npx wrangler deploy。展开 Build variables，将你 .env 中的所有环境变量填入其中。全部完成之后点击 Connect。
  3. 同样在 byrdocs 站点设置中，找到 Domains & Routes，点击 +Add -> Custom domain，填写你希望使用的域名。
  4. 提交你在第 4 步中作出的更改并推送到 GitHub。接下来检查 Cloudflare Deployment 是否可以正常运行并通过。

现在你已经顺利搭建好了 BYR Docs 的开发环境。

准备 BYR Docs 文件 ​

  • BYR Docs 的资源文件位于一个 Cloudflare R2 存储桶内，它们分为三类：
    • 文件本身，它的 MD5 校验码等于文件名，后缀只能是 .zip 或 .pdf。
    • 文件附属的 .webp 文件，用于网页预览。
    • 文件附属的 .jpg 文件，用于大图预览。
  • BYR Docs 的数据文件位于另一个 Cloudflare R2 存储桶内，有且只有 5 个：
    • metadata.json 记录 byrdocs-file 中文件的信息，以供后台处理。
    • book.yaml test.yaml doc.yaml 都来自 byrdocs-archive 仓库。
    • sitemap.xml 用于为搜索引擎提供索引，它是随着有关GitHub Workflow自动生成和上传的，你无需手动准备。
  • 另外，建议你准备一个备份存储桶，以防不测。
    • 你只需要存储资源文件中的 .zip 和 .pdf 文件，因为 .webp .jpg 文件都是由前者生成的，无需专门存储。

当你下载 BYR Docs 资源文件压缩包后，请先将其解压，得到一个名为 byrdocs-file/ 的文件夹。接下来，你可按以下步骤，将资源文件导入你自己账号下的 R2 存储桶中。

  1. 建立三个 R2 存储桶，分别名为 byrdocs-file byrdocs-data 和 byrdocs-backup。但不要修改现有的 wrangler.toml。
bash
npx wrangler r2 bucket create byrdocs-file
npx wrangler r2 bucket create byrdocs-data
npx wrangler r2 bucket create byrdocs-backup
  1. 建立一组可以通过 Minio 访问并读写以上三个存储桶的 Token。在创建 R2 API Tokens 页面中为 byrdocs-file byrdocs-data byrdocs-backup 存储桶授予 Object Read & Write 权限，如下图所示。 Creating R2 Token
  2. 当 Token 建立成功后，注意记录并保存完成页面的 Token value, Access Key ID, Secret Access Key 及以 S3 Endpoint。
  3. 通过 Minio 建立一个到你账号 R2 存储池的引用，其中的 <s3-endpoint> <access-key-id> <secret-access-key> 都是第 3 步中你记录下的值。
bash
mcli alias set r2 <s3-endpoint> <access-key-id> <secret-access-key>
  1. 通过 Minio 进行文件拷贝。来源目录为你解压得到的 byrdocs-file/ 目录，目标目录为 r2/byrdocs-file 存储桶。
bash
mcli cp -r ./byrdocs-file/ r2/byrdocs-file
  1. 拷贝完成后，可以通过 diff 检查 byrdocs-file 存储桶的数据是否完整。如果数据不完整，请回到上一步。
bash
mcli diff ./byrdocs-file/ r2/byrdocs-file # 如无任何输出且返回值为 0，则数据完整
  1. 为 byrdocs-data 建立一个自定义域名，这样，包括你在内的任何人都可以使用域名来读取其中的文件。其中的 $ZONE_ID 可以如此查询。
bash
# 其中的 $R2_DATA_SITE_URL 不要带 `https://` 前缀
npx wrangler r2 bucket domain add byrdocs-data --domain $R2_DATA_SITE_URL --zone-id $ZONE_ID

准备 BYR Docs Archive ​

  1. 将 byrdocs-archive 仓库拷贝到本地，并进入该目录。
  2. 使用以下命令来批量修改元信息中的 url，其中 BYRDOCS_SITE_URL 是你为主站设定的目标域名，例如 https://byrdocs.org。
bash
pip install -r scripts/requirements.txt
scripts/update_urls.py $BYRDOCS_SITE_URL
  1. 上传 GitHub Secrets，以便应用于 GitHub Actions 当中。一共有 12 个 Secrets 需要上传：
    1. R2_ACCOUNT_ID 是你的 Cloudflare Account Id；
    2. R2_ACCESS_KEY_ID R2_SECRET_ACCESS_KEY 是你在创建 R2 Token 时记录下来的值。
    3. R2_FILE_BUCKET R2_DATA_BUCKET 是你定义的资源文件存储桶、数据存储桶名称，在这里是 byrdocs-file byrdocs-data。
    4. BYRDOCS_SITE_URL 是你为主站设置的网站域名 $BYRDOCS_SITE_URL。
    5. BYRDOCS_SITE_TOKEN 是你在 byrdocs 代码中定义的 BYRDOCS_SITE_TOKEN 值，需保持一致。
    6. FILELIST_SITE_URL 定义了 .zip 文件预览服务的 API 提供网站。你可直接使用 https://filelist.youxam.workers.dev/png。
    7. BACKUP_ENDPOINT 是你 R2 备份存储池的 S3 API 端点，可在 Account Details 中查得。当然，你也可以自行配置和使用其它 S3 兼容的存储池。
    8. BACKUP_ACCESS_KEY_ID BACKUP_SECRET_ACCESS_KEY 是你在创建 R2 备份存储池的 Token 时记录下来的值。如果你的备份存储池和主存储池相同，只需使用第二步中相同的值即可。
    9. BACKUP_FILE_BUCKET 是你定义的资源文件备份存储桶名称，在这里是 byrdocs-backup。
  2. 在该仓库的设置页中，找到 Actions -> General -> Actions Permissions，选择 Allow all actions and reusable workflows，以启用 GitHub CI。
  3. 在该仓库的 Actions 页中，如果出现了 Workflows aren't being run on this forked repository 提醒，点击 I understand my workflows, go ahead and enable them，以确认启用 Workflows。
  4. 提交你在第 2 步中作出的更改并推送到 GitHub。接下来检查 GitHub Workflows 是否可以正常运行并通过。
  5. 如果上一步顺利通过，你将可以使用 Minio CLI 看到 byrdocs-data 存储桶中出现了 metadata.json book.yaml test.yaml doc.yaml 四个文件。
bash
mcli ls r2/byrdocs-data

现在你已经顺利搭建好了 BYR Docs 主站的服务。

BYR Docs Publish ​

所需资料 ​

BYR Docs Publish 是一个 Cloudflare Page，其前后端代码位于 byrdocs-publish 仓库中。

你需要准备的资料包括：

  • 一个 byrdocs-publish 仓库，建议置于你自己的组织名下，作为基准仓库。你应当已经在准备 BYR Docs Archive 的过程中完成了这一步。
  • （可选）当你调试网站功能时，你需要准备另一个 byrdocs-publish 仓库。它必须由基准仓库 Fork 而来。

所需环境 ​

  • 你需要拥有一个 Cloudflare 账号。
  • 你的本地开发环境需要安装 Node.js 及 pnpm。
  • 本项目的最佳布署方法是使用 Wrangler CLI。它作为 byrdocs-publish 仓库的依赖包，在 准备开发环境 一步中可以安装。
  • 强烈建议你注册一个 GitHub 组织，或拥有两个 GitHub 账户，否则你将无法 Fork 自己的 byrdocs-archive 仓库并使用部分功能。
  • 你需要创建一个 GitHub APP 并拥有其完整权限，我将在下文介绍其配置。

搭建步骤 ​

分为以下几个子步骤：

  1. 准备 GitHub App
  2. 准备 publish 开发环境

准备 GitHub App ​

要注册一个 GitHub App，你可以在个人或组织账户下完成，效果相同。接下来以在个人账户下注册为例：

  1. 打开新建 GitHub App页面。
  2. 填写 App 的有关配置。（假设你的 BYR Docs Publish 站点域名为 PUBLISH_SITE_URL）
    1. GitHub App Name 和 Homepage URL 都可以任意填写。
    2. Identifying and authorizing users：
      1. Callback URL 填为 PUBLISH_SITE_URL/callback/github；如果你希望在本地运行和测试，还可以添加一个 http://localhost:3000/callback/github。
      2. 选中 Expire user authorization tokens。
      3. 不选中 Request user authorization (OAuth) during installation 和 Enable Device Flow。
    3. Post installation：
      1. Setup URL 填为 PUBLISH_SITE_URL/bind。
      2. 选中 Redirect on update。
    4. Webhook：
      1. Webhook URL 填为 PUBLISH_SITE_URL/api/github/webhook。
      2. Secret 请自行生成一个足够强的字符串填入，记下它，作为 WEBHOOK_SECRET。
    5. Permissions：
      1. 在 Repository permissions 中，设定 Contents, Pull Requests 和 Workflows 的权限均为 Read and Write，其它项无需设定。
    6. Subscribe to events：不选任何项。
    7. Where can this GitHub App be installed? 选择 Any Account。
  3. 点击 Create GitHub App，完成 App 创建。
  4. 在完成创建的页面，记下 About 中的 App ID 和 Client ID，作为 APP_ID 和 GITHUB_CLIENT_ID。
  5. 在 Client Secrets 中点击 Generate a new client secret，记下新生成的值，作为 GITHUB_CLIENT_SECRET。
  6. 在 Private keys 中点击 Generate a private key，会生成并自动下载一个 .pem 文件。将它转成 PKCS8 格式，得到如下形式的内容。记下它的内容，作为 GITHUB_APP_PRIVATE_KEY。
-----BEGIN PRIVATE KEY-----
... ...
-----END PRIVATE KEY-----
  1. 点击侧边栏 Install App，将你创建的 GitHub App 安装到基准仓库中。

以上过程中需要你记录的量有五个：APP_ID GITHUB_CLIENT_ID GITHUB_CLIENT_SECRET GITHUB_APP_PRIVATE_KEY WEBHOOK_SECRET。请注意留存。

准备 publish 开发环境 ​

  1. 将 byrdocs-publish 仓库拷贝到本地，并进入该目录。
  2. 下载依赖。
bash
pnpm i
  1. 登录 Wrangler CLI，按照指示完成登录。
bash
npx wrangler login
  1. 配置 D1 数据库。
    1. 打开 wrangler.toml，删除所有的 [[d1_databases]] 表项。
    2. 创建名为 byrdocs-publish，绑定名为 DB 的 D1 数据库。
    bash
    npx wrangler d1 create byrdocs-publish --binding DB
    1. Wrangler 会为你生成一则 Toml 配置，将其复制到 wrangler.toml 中，如：
    toml
    [[d1_databases]]
binding="DB"
database_name = "byrdocs-publish"
database_id = $DATABASE_ID
    1. 应用 D1 数据库迁移。
    bash
    npx wrangler d1 migrations apply byrdocs-publish --remote
  2. 填写环境变量。你需要准备以下两个文件：
    1. wrangler.toml 的 [vars] 表中定义了构建时用到的环境变量，格式如下，请依实际情况自行更改。
    toml
    [vars]
# Node.js 版本，使用 23.9.0
NODE_VERSION = "23.9.0"
# 主站网址，也是你为主站设定的自定义域名
NEXT_PUBLIC_BYRDOCS_SITE_URL = "https://byrdocs.org"
# byrdocs-data 存储桶的自定义域名
NEXT_PUBLIC_R2_DATA_SITE_URL = "https://files.byrdocs.org"
# BYR Docs Publish 的域名，见下文第 11 步
NEXT_PUBLIC_PUBLISH_SITE_URL = "https://publish.byrdocs.org"
# 测试用的网站域名
NEXT_PUBLIC_PUBLISH_DEV_SITE_URL = "http://localhost:3000"
# 你的 GitHub APP 链接
NEXT_PUBLIC_PUBLISH_APP_URL = "https://github.com/apps/byrdocs-publish"
# 你的基准仓库所有者
NEXT_PUBLIC_ARCHIVE_REPO_OWNER = "byrdocs"
# 你的基准仓库名称
NEXT_PUBLIC_ARCHIVE_REPO_NAME = "byrdocs-archive"
# 你的基准仓库地址
NEXT_PUBLIC_ARCHIVE_REPO_URL = "https://github.com/byrdocs/byrdocs-archive"
    1. .dev.vars 定义了 Cloudflare 后端用到的环境变量，格式如下，请依实际情况自行更改。
    ini
    # 你在创建 GitHub APP 时记录下来的信息
APP_ID=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_APP_PRIVATE_KEY=
WEBHOOK_SECRET=
# 必须与 BYR Docs 主站使用的 JWT_SECRET 一致
JWT_SECRET=
  3. 现在将你的更改提交、推送到 GitHub。
  4. 开始通过 GitHub 布署 Cloudflare Page。从该账号名下的全部仓库中选择你的 byrdocs-publish 仓库，然后点击右下角 Begin setup。
  5. 选择正确的 branch。在 Build settings 中，Build command 填 pnpm run cf-build，Build output directory 留空。
  6. 点击 Save and Deploy，等待初次布署完毕。
  7. 接下来，将 .dev.vars 中的环境变量上传至 Cloudflare Worker 中。
bash
npx wrangler pages secret bulk .dev.vars
  1. 在 Workers & Pages 列表中，选中自己的 byrdocs-publish 站点。找到 Custom domains，点击 Set up a custom domain，填写你希望使用的域名，再点击 Continue -> Active domain，激活此域名。
  2. 再次通过 GitHub 仓库布署。一种可行的方法是重新提交并推送到 GitHub：
bash
git commit --amend
git push origin main --force-with-lease

维基真题 ​

维基真题基于 Astro 搭建搭建，可以快捷、简单地生成内容呈现网站。无论要在本地搭建，还是使用 Pages 服务，都十分方便。

你可以选择使用自托管服务器或 Cloudflare Pages （及其它 Pages 服务）搭建本站。不过一般来说，即便你选择了 Pages 服务，为了测试网站效果，本地搭建和预览也是必要的。

所需资料 ​

维基真题的全部文件是一个 GitHub 仓库，你可直接 Fork 该仓库。

本地搭建 ​

需要安装 Node.js 及 pnpm。

  1. 将该仓库内容克隆到本地，打开所在目录。
  2. 下载依赖。
bash
pnpm i
  1. 启动开发服务器。访问 http://localhost:4321，你可以看到网站的内容，并使用一些基本功能。在 dev 模式下，这个网站会随着你的文档代码更新而热加载。
bash
pnpm dev # 开始 dev 预览模式
  1. 注意，不是所有功能都能在预览模式下测试。如果你需要，请构建完整网页并使用它的全部功能。
bash
pnpm build # 此时网页代码将被编译至 `dist/` 中
pnpm preview # 本地查看，也可加 --host 暴露给公网

使用 Cloudflare Pages 搭建 ​

需要拥有一个 Cloudflare 账号。如果只需搭建维基真题，你无需付费或填写任何付款方式。

  1. 开始通过 GitHub 布署。初次使用时，你可能需要绑定一个 GitHub 账号。绑定账号之后，从该账号名下的全部仓库中选择你的仓库，然后点击右下角 Begin setup。
  2. 在配置列表中，需要指定 Framework preset 为 Astro，Build command 为 pnpm build，Build output directory 为 dist，其它配置可以自行修改。配置完毕后点击右下角 Save and Deploy，开始部署你的网站。 Set up builds and deployments
  3. 等待 Cloudflare 布署完毕，而后你可以查看该网站。

此时该 Page 已经与你绑定的 GitHub 仓库建立连接。每当 GitHub 仓库发生更新时，该 Page 都会获取更新并重新布署，非常方便。

完善 wiki.json ​

在 /wiki.json 路径下你可以看到一系列试题元信息。如果你需要搭建主站，主站会使用这些信息查询并列出维基真题的页面。

如果你需要在本地搭建，你可以在 .env 中填写构建时环境变量，格式如下，请依实际情况自行更改：

ini
WIKI_SITE_URL=https://wiki.byrdocs.org

如果你需要在 Cloudflare Pages 中搭建，请修改 wrangler.toml 中的 WIKI_SITE_URL 一项，再进行布署。

BUPT 生存指南 ​

BUPT 生存指南基于 Astro Starlight 搭建，可以快捷、简单地生成静态的文档网站。无论要在本地搭建，还是使用 Pages 服务，都十分方便。

你可以选择使用自托管服务器或 Cloudflare Pages （及其它 Pages 服务）搭建本站。不过一般来说，即便你选择了 Pages 服务，为了测试网站效果，本地搭建和预览也是必要的。

接下来我将介绍如何本地搭建和使用 Cloudflare Pages 搭建。

所需资料 ​

BUPT 生存指南的全部文件是一个 GitHub 仓库，你可直接 Fork 该仓库。

本地搭建 ​

需要安装 Node.js 及 pnpm。

  1. 将该仓库内容克隆到本地，打开所在目录。
  2. 下载依赖。
bash
pnpm i
  1. 启动开发服务器。访问 http://localhost:4321，你可以看到网站的内容，并使用一些基本功能。在 dev 模式下，这个网站会随着你的文档代码更新而热加载。
bash
pnpm dev # 开始 dev 预览模式
  1. 完成文档工作后，你可以构建完整网页并使用它的全部功能。
bash
pnpm build # 此时网页代码将被编译至 `dist/` 中
pnpm preview # 本地查看，也可加 --host 暴露给公网

使用 Cloudflare Pages 搭建 ​

需要拥有一个 Cloudflare 账号。如果只需搭建 BUPT 生存指南，你无需付费或填写任何付款方式。

  1. 开始通过 GitHub 布署。初次使用时，你可能需要绑定一个 GitHub 账号。绑定账号之后，从该账号名下的全部仓库中选择你的仓库，然后点击右下角 Begin setup。
  2. 在配置列表中，需要指定 Framework preset 为 Astro，Build command 为 pnpm build，Build output directory 为 dist，其它配置可以自行修改。配置完毕后点击右下角 Save and Deploy，开始部署你的网站。 Set up builds and deployments
  3. 等待 Cloudflare 布署完毕，而后你可以查看该网站。

此时该 Page 已经与你绑定的 GitHub 仓库建立连接。每当 GitHub 仓库发生更新时，该 Page 都会获取更新并重新布署，非常方便。

Last updated:

BYR Docs Blog

Copyright © 2025 BYR Docs