本站更新指南：如何发布文章与更新网站

这是本站的第一篇文档，用于记录日常更新文章和维护网站的完整流程。以后忘记怎么操作时，直接打开这篇文章即可。

一、环境准备

本站使用 Astro 7 构建，要求 Node.js 22.12 以上版本，包管理器使用 pnpm 11。

1
# 加载 Node（服务器上通过 NVM 安装）
2
source ~/.nvm/nvm.sh
3

4
# 进入项目目录（按实际存放路径修改）
5
cd /path/to/astro-yi
6

7
# 安装依赖
8
pnpm install

如果是在新电脑上操作，需要先安装 Node 22 和 pnpm：

1
nvm install 22
2
nvm use 22
3
npm install -g pnpm@11

二、发布一篇新文章

1. 新建 Markdown 文件

文章统一放在 src/content/blog/ 目录，新建一个 .md 文件即可。文件名会成为文章 URL 的一部分，建议使用英文短横线命名：

1
src/content/blog/my-first-note.md

对应访问地址：

1
https://www.772288.xyz/blog/my-first-note

2. 编写文章头部信息

文件顶部需要一段 frontmatter，常用字段如下：

1
---
2
title: 文章标题
3
date: 2026-10-20
4
description: 用一两句话概括文章内容，会显示在列表和搜索结果中。
5
tags: [学习, 笔记]
6
category: 学习记录
7
sticky: 0
8
draft: false
9
toc: true
10
---

3. 编写正文

frontmatter 下方直接写 Markdown 正文即可。常用写法：

1
## 二级标题
2

3
这是一段正文，支持**加粗**、*斜体*、[链接](https://example.com) 和行内代码。
4

5
- 列表项一
6
- 列表项二
7

8
> 这是引用内容。

插入图片时，先把图片放到 public/images/ 目录，然后在文章中引用：

1
![图片说明](/images/example.png)

代码块直接使用三个反引号：

1
```js
2
console.log('Hello')
3
```

4. 本地预览

保存文件后启动开发服务器：

1
pnpm dev --host 0.0.0.0 --port 4321

浏览器访问 http://localhost:4321 查看效果。开发模式下，标记为草稿的文章也会显示。

5. 修改和删除文章

• 修改：直接编辑对应的 .md 文件，页面会自动刷新。
• 删除：删除对应的 .md 文件即可。
• 改文件名：文章 URL 会同步变化，已有外部链接可能失效，操作前请确认。
• 分类页、标签页、归档页和 RSS 会根据文章内容自动重新生成。

三、修改站点配置

站点配置集中在 src/consts.ts，为了以后能顺利合并主题更新，不要修改组件、布局和 i18n 文件。

常用配置：

换域名时，务必同时修改 site.url，否则 canonical、sitemap 和 RSS 仍会指向旧域名。

关于页内容位于 src/pages/about/about.md，可以直接修改；但这是主题文件，合并主题更新时可能会产生冲突，需要手动保留自己的内容。

四、构建并检查

发布前先执行生产构建：

1
pnpm build

构建完成后，产物位于 dist/ 目录。建议再用预览命令检查一次：

1
pnpm preview --host 0.0.0.0 --port 4321

重点检查：

• 新文章能否正常打开
• 分类、标签、归档是否正确
• 页脚备案号是否正常显示
• 图片和代码块是否正常
• 页面源码中的 canonical 是否为正式域名

五、提交到自己的 Git 仓库

项目的 origin 指向自己的 Git 仓库，upstream 指向原主题仓库，可用 git remote -v 查看。

1
git status
2
git add src/content/blog/new-post.md
3
git commit -m "post: 新增文章"
4
git push origin main

注意：

• 只提交文章、图片和 src/consts.ts 配置。
• 不要提交 API Token、密码、.env 或其他密钥文件。
• 提交前先看一遍 git status，确认没有把构建产物 dist/ 一起提交。

六、部署到 EdgeOne Makers

本站通过 EdgeOne Makers 中国大陆站部署，使用 edgeone CLI 上传构建产物。

1. 安装并登录 CLI

1
npm install -g edgeone
2
edgeone login -s china

如果是在 CI 或其他无法打开浏览器的环境中，可以使用 API Token 登录：

1
edgeone login -s china -t "$EDGEONE_API_TOKEN"

Token 在 EdgeOne Makers 控制台的「API Token」页面创建，建议设置较短的有效期，部署完成后及时撤销。

2. 构建并部署

1
cd /path/to/astro-yi
2
pnpm build
3
edgeone makers deploy ./dist -n astro-yi

• 默认部署到生产环境。
• 如需先发布预览版本，可添加 -e preview。
• 部署成功后，CLI 会输出访问地址和控制台链接。
• 中国大陆站控制台：https://console.cloud.tencent.com/edgeone/makers

3. 域名与 HTTPS

首次部署后需要把 www.772288.xyz 绑定到项目：

1. 打开 EdgeOne Makers 控制台，进入对应项目。
2. 切换到「域名管理」，点击「添加自定义域名」。
3. 输入 www.772288.xyz。
4. 按控制台提示，在域名服务商处添加 CNAME 记录，指向 EdgeOne 提供的目标地址。
5. 等待 DNS 生效和证书签发，然后开启强制 HTTPS。

中国大陆站使用自定义域名必须完成 ICP 备案。本站备案号是「苏ICP备2023044985号」，页脚会自动读取配置并展示。

七、更新主题

原主题仓库保留在 upstream 远程中，需要同步主题更新时执行：

1
git fetch upstream
2
git merge upstream/main
3
pnpm install
4
pnpm build

如果提示 upstream 不存在，先添加：

1
git remote add upstream https://github.com/cirry/astro-yi.git

合并时只需要重点关注 src/consts.ts、文章内容和关于页，其余文件尽量保持主题原样，这样后续更新会更顺利。测试无误后重新部署：

1
edgeone makers deploy ./dist -n astro-yi

八、日常最短操作流程

1
# 1. 写文章
2
vim src/content/blog/new-post.md
3

4
# 2. 本地预览
5
pnpm dev --host 0.0.0.0 --port 4321
6

7
# 3. 提交代码
8
git add src/content/blog/new-post.md
9
git commit -m "post: 新增文章"
10
git push origin main
11

12
# 4. 构建并部署
13
pnpm build
14
edgeone makers deploy ./dist -n astro-yi

最后访问 https://www.772288.xyz 检查文章、备案号和 HTTPS 是否正常。

九、常见问题

文章没有出现在线上？

检查 draft 是否为 true，确认已经重新执行 pnpm build 并完成部署。

文章地址 404？

确认文件名和访问地址一致，注意不要随意修改已发布文章的文件名。

部署提示 Token 无效？

Token 可能已过期，或者不是中国大陆站的 Token。请重新创建 Token 并确认使用了 -s china。

域名打不开？

依次检查 CNAME 是否生效、HTTPS 证书是否签发、域名备案是否有效，以及 site.url 是否填写正确。

构建失败？

先确认 Node.js 版本不低于 22.12，然后删除 node_modules 重新执行 pnpm install 和 pnpm build。