建站记录模板

建站记录不是泛泛的部署教程，而是针对本站一次真实变更的可追溯记录：改了什么、在什么环境、如何验证、出错时怎样回滚。它应该让未来的自己能在半年后重新看懂这次操作。

用途

记录域名、DNS、HTTPS、部署平台、构建命令和环境变量的变更。
记录评论系统、CDN、图床、搜索、统计或主题配置的接入过程。
保存变更前后的验证结果，确认线上真的生效。
为高风险操作留下可执行的回滚步骤和责任人。

放在哪里

建站记录仍然是文章，放在 docs/posts/ 下；通常归入 技术笔记，可放在一级目录或「项目记录」等二级目录。

场景	目标文件	`categories`	`permalink`	公开地址
技术笔记一级目录	`docs/posts/技术笔记/10.edgeone-deploy.md`	`[技术笔记]`	`/posts/技术笔记/edgeone-deploy`	`https://www.baecon.cn/posts/技术笔记/edgeone-deploy`
项目记录子目录	`docs/posts/技术笔记/项目记录/20.comment-system-record.md`	`[技术笔记]`	`/posts/技术笔记/项目记录/comment-system-record`	`https://www.baecon.cn/posts/技术笔记/项目记录/comment-system-record`

公式：

text

文件：docs/posts/<一级分类>/[<子目录>/]<slug>.md
permalink：/posts/<一级分类>/[<子目录>/]<slug>
公开地址：https://www.baecon.cn/posts/<一级分类>/[<子目录>/]<slug>

「项目记录」只进入文件路径和 URL，不进入 categories。目录页入口应单独放在 docs/catalog/。

什么时候使用

对本站做了一次会影响线上访问、构建、域名、评论或统计的变更。
需要记录变更前的状态、变更步骤、验证结果和回滚方式。
配置涉及多个平台，未来排错时需要还原上下文。
变更可能产生费用、安全风险、数据不可逆或较长缓存时间。

什么时候不要使用

想写一篇面向所有读者的通用部署教程：使用技术教程模板。
想记录项目整体目标、方案和结果指标：使用项目复盘模板。
只是一次普通的代码改动，没有平台配置、线上验证或回滚需求：使用通用文章模板。
准备把真实 Token、密码、私钥、Cookie、数据库连接串写入文章。任何情况下都不要这样做。
变更尚未完成，回滚方式也未确定。应先准备变更方案，再开始操作和记录。

完整可复制文件

markdown

---
title: EdgeOne Pages 部署记录
description: 记录博客迁移到 EdgeOne Pages 的真实操作，包含环境版本、构建命令、部署步骤、线上验证、问题处理、回滚方式、敏感信息保护和持续后续检查。
permalink: /posts/技术笔记/项目记录/edgeone-deploy
categories:
  - 技术笔记
tags:
  - 建站
  - EdgeOne
  - 部署
article: true
sidebar: true
pagefind-indexed: true
comment: true
---

# EdgeOne Pages 部署记录

用两三句话交代这次变更的对象、时间和最终结果，并明确这是一次真实操作的记录，不是通用教程。不要在开头写任何密钥、账号或内部地址。

## 目标

- 把博客构建产物部署到 EdgeOne Pages。
- 保持现有域名和文章永久链接可访问。
- 确认搜索、评论、统计和 RSS 在线上正常。
- 准备在部署失败时恢复上一版本的方法。

本次不处理：主题视觉重做、文章内容迁移和 CDN 缓存策略的全面优化。

## 环境

| 项目 | 本次实际值 | 备注 |
|---|---|---|
| 域名 | `www.baecon.cn` | 公开域名，可记录 |
| 仓库 | 私有仓库地址 | 不要公开内部仓库、凭据和邀请链接 |
| 部署平台 | EdgeOne Pages | 记录项目名和区域时先脱敏 |
| 构建环境 | Node.js 20.x、pnpm 9.x | 写实际版本 |
| 构建命令 | `pnpm docs:build` | 与 CI 保持一致 |
| 产物目录 | `docs/.vitepress/dist` | 发布前确认路径 |
| 环境变量 | `EDGEONE_PAGES_API_TOKEN` | 只记录变量名，不记录值 |

敏感信息只写变量名和配置位置，不写明文：

```text
正确：EDGEONE_PAGES_API_TOKEN 配置在部署平台的加密环境变量中
错误：EDGEONE_PAGES_API_TOKEN=真实值
```

## 操作步骤

### 1. 记录变更前状态

确认旧版本仍可访问，记录关键页面和当前提交：

```bash
git rev-parse --short HEAD
curl -I https://www.baecon.cn/
```

预期：命令输出当前提交哈希，首页返回 `200`。把旧提交哈希和部署版本记录下来，作为回滚目标。

### 2. 本地安装与构建

```bash
pnpm install --frozen-lockfile
pnpm docs:build
```

预期：依赖安装成功，构建退出码为 `0`，`docs/.vitepress/dist/` 生成。

### 3. 检查构建产物

```bash
Test-Path docs/.vitepress/dist/index.html
```

预期输出 `True`。同时确认 `docs/.vitepress/dist/assets/` 和搜索索引已经生成。

### 4. 配置环境变量

在部署平台中把 Token 保存为加密环境变量，变量名使用：

```text
EDGEONE_PAGES_API_TOKEN
```

不要写入 Markdown、Git、截图、命令历史或公开日志。只记录变量名、配置位置和权限范围。

### 5. 执行部署

在 CI 或手动部署环境中执行，具体命令以仓库当前配置为准：

```bash
npx edgeone makers deploy ./docs/.vitepress/dist -n my-blog-teek -t $EDGEONE_PAGES_API_TOKEN
```

预期：命令退出码为 `0`，平台返回部署成功和预览地址。不要截取包含完整命令参数、Token 或账号信息的终端画面。

## 验证结果

逐项验证，不只看部署面板显示成功：

| 检查项 | 方法 | 预期结果 |
|---|---|---|
| 首页可访问 | `curl -I https://www.baecon.cn/` | `HTTP/2 200` |
| 文章页可访问 | 抽查旧文章和新文章 URL | 返回 `200`，正文正常 |
| 静态资源 | 检查 CSS、JS 和图片控制台 | 没有 404 或 MIME 类型错误 |
| 搜索 | 搜索文章关键词 | 能返回正确文章 |
| 评论 | 打开一篇文章评论区 | 能加载，且未暴露配置密钥 |
| RSS | 打开 `/feed.xml` 或实际 RSS 地址 | 返回有效 XML |
| 移动端 | 用手机宽度检查首页和文章页 | 无横向溢出和遮挡 |

```bash
curl -I https://www.baecon.cn/
```

预期输出包含：

```text
HTTP/2 200
content-type: text/html
```

![EdgeOne 部署成功的控制台截图，敏感信息已打码](/images/posts/edgeone-deploy/dashboard.webp)

> 图片提示：必须遮盖项目 ID、账号、Token、内部链接和访问统计；没有安全截图时删除这一行。

## 问题与回滚

记录真实问题、影响、临时处理、根因和最终结果。

| 问题 | 影响 | 原因 | 处理方式 | 是否回滚 |
|---|---|---|---|---|
| 首页静态资源 404 | 页面样式丢失 | 产物目录配置错误 | 修改部署目录后重新构建部署 | 否 |
| 评论加载失败 | 文章页评论区空白 | 环境变量缺失 | 在加密环境变量中补齐后重新部署 | 否 |
| 部署后旧链接 404 | 影响已有分享链接 | 重写规则变化 | 恢复原永久链接配置并重新部署 | 是 |

### 回滚步骤

1. 立即停止继续修改线上配置，保留错误日志和截图。
2. 在部署平台选择上一个稳定版本，或回退到变更前记录的提交哈希。
3. 恢复被修改的环境变量、域名、DNS、重写规则或缓存配置。
4. 重新触发部署，等待状态变为成功。
5. 重新检查首页、文章页、静态资源、搜索、评论和 RSS。
6. 在本文补记回滚时间、原因、影响范围和后续行动。

## 备注

- 记录平台限制、免费额度、计费和续费日期，但不要写账号凭据。
- 记录 CDN 缓存时间、DNS TTL 和生效等待时间。
- 记录后续需要补充的监控、告警、备份或权限回收。
- 涉及第三方平台时，保留官方文档链接和变更日期。

复制后必须修改或确认

值	位置	应该怎么改	为什么必须确认
`title` 和正文 H1	frontmatter 与 `# EdgeOne Pages 部署记录`	改成完全一致的真实建站记录标题	页面只能有一个 H1，标题会进入首页、侧边栏和搜索。
`description`	frontmatter	换成 50–150 个中文字符的真实摘要	说明本次变更对象、结果和风险，不要泄露内部信息。
`date`	frontmatter	通常不要手填；文件首次 Git commit 后启动/构建会自动写入	自动写入后不要为了「更新」而改它；更新信息用 `updated`。
`permalink`	frontmatter	改成全站唯一且匹配目录的 `/posts/...` 地址	建站记录也需要稳定链接，便于回看和引用。
`categories`	frontmatter	只写一级分类，通常是 `[技术笔记]`	「项目记录」等二级目录不是分类。
`tags`	frontmatter	换成 2–5 个建站主题标签	如建站、部署、CDN、评论；不要写凭据或内部系统名。
`coverImg`	frontmatter	通常删除以使用正文图片/随机背景；只在需要固定卡片或分享图时写真实路径	显式写后会固定，不再随机；路径必须存在。
`article`	frontmatter	保持 `true`	确保记录作为文章进入首页和归档。
`sidebar`	frontmatter	保持 `true`	正常文章显示侧边栏。
`pagefind-indexed`	frontmatter	保持 `true`；如含内部信息则不要发布	搜索索引不是访问控制。
`comment`	frontmatter	保持 `true`，或按安全需要改 `false`	评论区可能被追问配置细节；敏感内容不要发布。
环境变量和平台信息	body	只写变量名和配置位置，绝不写真实值	Token、密码、Cookie、私钥不得进入 Git 和文章。
步骤、验证和回滚	body	换成本次真实命令、实际输出、真实结果和可执行回滚	示例命令和表格不能直接当作已完成的记录。
截图与 alt	body	使用真实且已打码的截图，alt 描述安全检查后的内容	路径采用 `/images/posts/<slug>/<file>.webp`。

可选字段

字段	什么时候用	推荐值	注意
`titleTag`	想标示这是一篇建站记录	`记录`	只是标题旁短标签，不替代 tags。
`top`	需要进入首页精选	`1`	只适合对读者有长期价值且已脱敏的记录。
`sticky`	需要置顶排序	`1` 或较小数字	必须是数字，越小越靠前。
`sidebarSort`	需要覆盖侧边栏顺序	`10`、`20`	优先使用文件名数字前缀。
`inHomePost`	不想让记录进入首页主列表	省略或 `false`	会影响首页及分类/标签的 HomePost 列表，不是隐私开关。
`updated`	变更补充后需要覆盖 SEO 修改时间	`YYYY-MM-DD HH:mm:ss`	通常省略，不能代替 `date`。
`author`	多人协作且需要署名	不写；如确需覆盖，用对象 `{ name, link }`	本站默认站点作者，普通记录不覆盖。

文章 frontmatter 字段总表

字段	类型	省略时默认	推荐值	级别	完整说明
`title`	`string`	无可用默认；不要依赖自动推导	与正文唯一 H1 完全一致	必填	页面标题，也是首页卡片、侧边栏、搜索结果和浏览器标题的来源。复制模板后必须改成真实标题，并保证正文只有一个 H1。
`description`	`string`	SEO 会回退到站点描述；首页摘要质量不可控	50–150 个中文字符，说明问题、内容与读者收益	推荐	供 SEO 描述、首页卡片摘要和分享信息使用。应写成完整的一句话或两句话，不要堆关键词，也不要直接复制标题。
`desc`	`string`	未设置	省略	可选（旧字段）	旧目录页的兼容显示字段，主要给 catalogue 页面使用；它不是 SEO 主字段，也不参与首页摘要。新文章不要写；目录页如保留 `desc`，需与 `description` 同值。
`date`	`string`	文件首次 Git commit 的作者时间；已有值保留	通常省略，不手填；需要人工指定发布时间时才覆盖	自动维护；通常不手填	文章的创建/发布时间，用于展示、首页排序、归档和 SEO 的 `datePublished`。新文章不需要写；首次 commit 后启动/构建会写入并保持稳定。
`updated`	`string`	未显式设置；SEO 修改时间由构建或最后更新时间兜底	正常省略；确实需要覆盖时再用同一日期格式	可选	只用于覆盖 SEO 的 `dateModified`，不是文章发布时间，也不能代替 `date`。除非有明确的更新日期要展示给搜索引擎，否则不要填。
`permalink`	`string`	自动插件通常跳过已有 frontmatter，不能依赖自动生成	全站唯一：`/posts/<一级分类>/[<子目录>/]<slug>`	必填	决定文章的公开 URL。本项目要求显式填写，不能包含 `.md`，不能以 `docs/` 开头，也不能与其他页面重复。
`categories`	`string[]`	自动插件通常跳过；缺省时没有可靠分类	显式写一级分类，如 `[技术笔记]`	推荐	分类归档和分类卡片使用。只写一级分类；二级目录属于路径，不是第二个分类。一篇文章通常只写一个一级分类。
`tags`	`string[]`	`[]`	2–5 个具体标签，如 `[VitePress, 部署]`	推荐	标签用于聚合主题和搜索。标签应短而具体，避免把整句话、分类名或大量近义词都写成标签。
`coverImg`	`string` 或 `string[]`	首页卡片：正文图片随机 → `/home/bg*.webp` 随机；SEO 分享图回退站点默认	需要固定封面/分享图时才写真实路径；否则省略	可选（按需）	首页卡片优先使用；文章 Banner、OG 和分享图也会读取。显式写后不再随机；路径必须真实存在；不写时分享图不会自动取正文图。
`article`	`boolean`	在 `/posts/` 下省略时按 `true` 处理	`true`	推荐	明确声明这是文章，让首页、归档、分类和标签等文章能力正常工作。教程、复盘、随笔、题解和建站记录都应显式写 `true`。
`sidebar`	`boolean`	VitePress 默认为 `true`	`true`	推荐	控制文章页是否显示左侧文章导航。本站文章应保持 `true`；只有特殊全宽页面才考虑关闭。
`sidebarSort`	`number`	使用文件名数字前缀；没有前缀时按 `9999`	省略；确需覆盖时用 `10`、`20` 这类数字	可选	覆盖该文章在侧边栏中的排序，数字越小越靠前。优先用文件名前缀排序；同时使用两种方式会增加理解和维护成本。
`pagefind-indexed`	`boolean`	`true`	`true`	推荐	控制 Pagefind 是否索引此页。文章应保持 `true`；设为 `false` 只是不进入站内搜索，并不会把页面变成私有页面。
`comment`	`boolean`	未写 `false` 时按开启处理	`true`	推荐	控制文章评论区。普通文章保持 `true`；目录页、纯功能页或含敏感信息的页面应关闭或不要发布。
`top`	`boolean 或 number`	未设置，即不进入精选	省略；只有需要首页精选时写 `1`	可选	首页「精选文章」的真值筛选标记，不是排名：写 `1` 表示入选，数字大小本身不会排序。是否显示还受首页精选数量上限影响。
`sticky`	`number`	未设置，即不置顶	省略；确需置顶时用较小数字，如 `1`	可选	置顶排序字段，数字越小越靠前。它和 `top` 分工不同：`top` 负责进入精选卡片，`sticky` 负责置顶排序。不要用 `true` 代替数字。
`inHomePost`	`boolean`	`true`	省略或显式 `true`；只有特殊文章才写 `false`	可选	设为 `false` 时会从首页、分类页和标签页等 HomePost 列表隐藏；文章的 URL、侧边栏、归档、精选和搜索等不会自动变成私有。不要把它当作隐私开关。
`inCatalogue`	`boolean`	`true`	通常省略；不想让文章出现在目录页时写 `false`	高级	目录插件扫描开关；不影响侧栏、Pagefind、首页、归档或 RSS。
`titleTag`	`string`	无标签	省略；需要短标识时用 `原创`、`教程`、`复盘`、`题解`、`记录`	可选	标题旁的小标签，只用于视觉提示，不替代分类或标签。保持 2–4 个汉字最清晰，不要塞入长句。
`author`	`object`	使用站点级作者 `Baecon`	省略，不在单篇文章覆盖	可选（不建议）	若覆盖需用 `{ name: string, link?: string }` 对象；普通文章不要填写。

高级 VitePress 字段

以下字段属于页面布局能力，不是建站记录字段。除非全站规范要求，否则全部省略。

字段	类型	省略时默认	推荐值	级别	完整说明
`layout`	`string 或 false`	使用 VitePress 标准文章布局	省略	高级	切换页面布局。文章模板不需要设置；目录页才固定使用 `layout: page`。初学者不要为了外观而改它。
`outline`	`false`、数字、`[number, number]` 或 `"deep"`	由 VitePress 与主题的默认大纲配置决定	省略	高级	控制右侧标题大纲。普通文章沿用站点统一配置即可，除非全站规范明确要求，否则不要逐篇覆盖。
`aside`	`boolean` 或 `"left"`	默认跟随 VitePress 文章布局	省略	高级	控制右侧辅助栏。与全站布局相关，不应由每篇文章随意切换。
`lastUpdated`	`boolean`	跟随站点 `lastUpdated: true`	省略	高级	控制页面是否显示最后更新时间。本站已统一开启，不需要在每篇文章重复设置。
`editLink`	`boolean`	跟随站点主题配置	省略	高级	控制是否显示编辑链接。它属于站点能力，不是文章内容字段。
`pageClass`	`string`	空	省略	高级	给页面根元素追加 CSS 类，只在有配套样式时使用。随意填写不会产生视觉效果。
`layoutClass`	`string`	空	省略	高级	当前项目会把它作为布局组件 class 读取，但只有配套 CSS 才有意义；普通写作不需要填写。
`head`	`array`	`[]`	省略	高级	为单个页面追加 `<head>` 标签。站点已统一生成 SEO 和分享标签，重复配置容易冲突。
`titleTemplate`	`string 或 false`	使用站点标题模板	省略	高级	覆盖浏览器标题拼接方式。除非页面有特殊 SEO 要求，否则不要覆盖全站一致性。
`autoTitle`	`boolean`	doc 布局默认允许自动注入 H1	省略；正文已手写 H1	高级	设为 `false` 可禁止自动 H1 注入。
`articleUpdate`	`boolean 或 object`	跟随站点配置，默认启用	省略	高级	设为 `false` 隐藏文章页最近更新模块。
`articleBanner`	`boolean 或 object`	跟随站点配置；本站开启	省略	高级	设为 `false` 关闭单文章 Banner；通常仅无侧栏 doc 文章生效。
`coverBgColor`	`string`	跟随站点 defaultCoverBgColor，本站为空	省略	高级	单文章 Banner 背景色覆盖；无 Banner 时不可见。
`prev`	`boolean`	`true`（有上一页时）	省略	高级	设为 `false` 隐藏上一页链接。
`next`	`boolean`	`true`（有下一页时）	省略	高级	设为 `false` 隐藏下一页链接。

catalogue、path、pageTitle 是目录页专用字段，文章模板不要填写。若需要创建分类或子目录入口，请使用目录页模板。

章节	写什么	示例
`## 目标`	这次变更要解决什么、覆盖什么、明确不做什么	用列表写目标和边界。
`## 环境`	域名、平台、构建版本、产物目录和变量名	只写变量名，不写真实凭据。
`## 操作步骤`	变更前状态、备份、实际命令和逐步结果	高风险操作前先记录回滚目标。
`## 验证结果`	首页、文章、资源、搜索、评论、RSS、移动端检查	写预期状态码或页面现象。
`## 问题与回滚`	真实问题、影响、处理方式、是否回滚和回滚步骤	回滚步骤要能由未来的自己直接执行。
`## 备注`	平台限制、费用、缓存、后续监控和官方链接	写清尚未解决的风险。