从零配置个人博客网站

从零配置个人博客网站

Jackknifer
Jackknifer 博主

个人博客可以保存学习笔记、生活见闻和自己的作品。你可以决定网站的样子,也可以为每篇文章保留一个长期使用的网址。搭建过程需要一些配置,但每一步都有可以检查的结果。

这篇教程面向第一次搭建博客的读者。从准备工具开始,你会逐步完成网站创建和公开发布。随后,你可以绑定自己的域名,并接入 Notion 写作。跟随教程操作时,请使用自己的账号和地址,完成一项后检查页面效果。[1][2][3]

1. 准备账号、工具和示例信息

1.1 准备所需工具

搭建博客需要一个 GitHub 账号、一台电脑和一个文本编辑器。本文使用 Hexo(静态网站生成工具)、Theme Redefine(博客主题)和 GitHub Pages(网页托管服务)。文章通过 Markdown(文本写作格式)保存,GitHub Actions(自动任务服务)负责生成和发布网页。

在电脑上安装 Node.js 24、Git 和 VS Code。Node.js 包含 npm(依赖管理工具);Git 用于提交文件,VS Code 用于编辑文章与配置。安装方法参见 Node.js 下载页面[4]和 GitHub 的 Git 安装指南[5]。

打开终端,逐行运行:

1
2
3
node --version
npm --version
git --version

三个命令都应显示版本号,Node.js 应显示 v24 开头的版本。出现“找不到命令”时,完成安装并重新打开终端。

1.2 确认需要替换的内容

本文的命令以 macOS 的 zsh 终端为例。安装完成后,Hexo 和 Git 的主要命令也适用于 Windows 与 Linux。文件可以直接使用 VS Code 创建和修改。

示例 需要替换为
USERNAME 自己的 GitHub 用户名
my-blog 电脑中保存博客的文件夹名称
example.com 自己购买的域名;没有域名时使用 GitHub 地址
你的名字、你的邮箱 自己的 Git 提交信息

后续命令均在博客根目录执行。这个目录包含 _config.yml 和 package.json。复制配置时保留原有缩进,YAML(配置文件格式)使用空格表示层级。

2. 创建博客并配置主题

2.1 初始化 Hexo

在准备保存博客的位置打开终端,运行:

1
2
3
4
5
npm install -g hexo-cli
hexo init my-blog
cd my-blog
npm install
npm install --save-exact hexo@8.1.2 hexo-theme-redefine@2.9.0

这里固定的是本文示例版本,不表示官方当前最新版或所有环境下已验证的兼容组合;更换版本时,应对照安装要求和主题文档重新检查。npm install 会生成 node_modules/ 和 package-lock.json。保留锁文件,后续在新电脑或 GitHub Actions 中使用 npm ci 安装相同依赖。安装流程参见 Hexo 安装文档[1]和初始化文档[6]。

使用 VS Code 打开 my-blog。在根目录创建 .nvmrc,内容填写 24。打开 .gitignore,确认包含以下规则;已有规则继续保留:

1
2
3
4
node_modules/
public/
db.json
.notion-local/

source/ 保存文章与图片,public/ 保存构建生成的网页。修改内容时编辑 source/,生成网页由 Hexo 管理。

2.2 修改网站信息

打开根目录的 _config.yml,找到对应项目并修改。保留其他配置,同一个项目只填写一次:

1
2
3
4
5
6
7
8
9
10
title: 我的个人博客
description: 记录学习、阅读和生活。
author: 你的名字
language: zh-CN
timezone: Asia/Shanghai
url: https://USERNAME.github.io
permalink: :year/:month/:day/:title/
date_format: YYYY-MM-DD
updated_option: date
theme: redefine

把 USERNAME 替换为自己的用户名。url 是网站的公开地址,permalink 决定文章网址。这里的网址包含发布日期和文件名称,文章发布后应保留这两项。

updated_option: date 让未填写更新时间的文章使用发布日期。各项含义参见 Hexo 配置文档[7]。

2.3 创建主题配置

  1. 在 VS Code 打开 node_modules/hexo-theme-redefine/_config.yml。
  2. 复制文件的全部内容。
  3. 在博客根目录创建 _config.redefine.yml,粘贴并保存。
  4. 在新文件中修改 info.title、info.author 和 info.url。
  5. 把 home.article_date_format 改为 YYYY-MM-DD。

例如,info.title 表示 info 下面的 title。在原有 info 配置中填写:

1
2
3
4
5
info:
title: 我的个人博客
subtitle: 记录学习与生活
author: 你的名字
url: https://USERNAME.github.io

需要头像时,把图片放入 source/images/avatar.jpg,再修改 defaults.avatar 为 /images/avatar.jpg。首页背景通过 home_banner.image.light 和 home_banner.image.dark 修改。

主题设置统一写入根目录的 _config.redefine.yml。完整说明参见 Theme Redefine 快速开始[2]。

2.4 检查本地网站

保存配置后运行:

1
2
3
npx hexo clean
npx hexo generate
npx hexo server

浏览器打开 http://localhost:4000/。应看到博客首页、主题样式和默认文章。确认网站名称已经改变,并检查终端有没有构建错误。预览结束后,在终端按 Ctrl+C。

3. 创建关于、分类和标签页面

3.1 创建页面文件

在博客根目录运行:

1
2
3
npx hexo new page about
npx hexo new page tags
npx hexo new page categories

打开 source/about/index.md,将标题改成“关于”,在开头的属性区域下面写个人介绍:

1
2
3
4
5
6
---
title: 关于
date: 2026-10-02 12:00:00
---

你好,这里记录我的学习、阅读和生活。

日期使用自己的创建日期。打开 source/tags/index.md,在属性区域加入 type: tags;打开 source/categories/index.md,加入 type: categories。页面标题分别填写“标签”和“分类”。

3.2 配置导航入口

打开 _config.redefine.yml,找到 navbar.links,修改为:

1
2
3
4
5
6
7
8
9
10
11
12
navbar:
links:
首页:
path: /
归档:
path: /archives/
标签:
path: /tags/
分类:
path: /categories/
关于:
path: /about/

这里展示需要修改的部分,navbar 中其他项目继续保留。保存后重新生成并预览,逐一点击导航。每个入口都应打开对应页面。分类和标签会随着文章属性更新。

4. 编写文章、添加图片和保存草稿

4.1 创建第一篇文章

运行以下命令,创建一个名称清楚的英文文件:

1
npx hexo new post first-post

打开 source/_posts/first-post.md,修改标题、日期和正文:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
---
title: 我的第一篇博客
date: 2026-10-02 12:00:00
tags:
- 博客
categories:
- 写作
description: 介绍我建立博客的原因,以及接下来想记录的内容。
---

## 为什么建立博客

我希望把学习笔记和生活记录保存下来。

## 接下来准备记录什么

- 阅读笔记
- 学习心得
- 旅行照片

文件顶部两条 --- 之间的内容称为 Front Matter(文章属性)。title 是网页标题,date 是发布日期,description 是摘要。分类用于较大的内容分组,标签用于具体主题。

标题可以使用中文,文件名称使用英文更便于管理网址。Markdown 中 ## 表示二级标题,- 表示列表。两段文字之间保留空行。文章格式参见 Hexo 写作说明[8]。

4.2 添加正文图片与封面

在 VS Code 中创建 source/images/posts/first-post/,把自己的照片放入这个目录。例如,文件为 photo.jpg 时,正文填写:

1
![照片说明](/images/posts/first-post/photo.jpg)

路径从 /images/ 开始,文件名称和大小写必须一致。图片更名后,同时修改正文地址。需要文章封面时,在 Front Matter 中增加:

1
cover: /images/posts/first-post/cover.jpg

将实际封面保存到对应位置。封面可以省略;正文图片可以单独使用。

4.3 保存未完成的文章

创建草稿并预览:

1
2
npx hexo new draft next-post
npx hexo server --draft

草稿保存在 source/_drafts/next-post.md。完成写作后,结束预览服务并运行:

1
2
3
npx hexo publish next-post
npx hexo clean
npx hexo generate

publish 将草稿移入正式文章目录。检查首页能否找到文章,并打开正文核对标题、日期、分类、标签和图片。

5. 上传 GitHub 并自动发布网站

5.1 创建个人站点仓库

  1. 登录 GitHub,点击“New repository”(新建仓库)。
  2. 仓库名称填写 USERNAME.github.io,替换为自己的用户名。
  3. 使用 GitHub Free 时选择公开仓库。
  4. 保持仓库空白,不勾选自动添加 README 等文件。
  5. 创建后打开 Settings → Pages。
  6. 在 Build and deployment → Source 选择 GitHub Actions。

例如,用户名为 reader,仓库名就填写 reader.github.io。仓库规则参见 GitHub Pages 入门文档[3]。私有仓库的 Pages 权限取决于 GitHub 方案,初次搭建可按公开仓库步骤操作。

5.2 添加发布工作流

在 VS Code 的博客根目录创建 .github/workflows/pages.yml,填写:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
name: Pages

on:
push:
branches: [main]
workflow_dispatch:

permissions: {}

concurrency:
group: pages
cancel-in-progress: false

jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: read
pages: read
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
with:
node-version: 24
cache: npm
- uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d
- run: npm ci
- run: npx hexo clean
- run: npx hexo generate
- uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9
with:
path: ./public

deploy:
needs: build
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- id: deployment
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128

这些项目依次完成依赖安装、网页生成、上传与部署。uses 后的长字符串固定 GitHub Action 的版本,完整复制即可。发布权限与任务关系参见 GitHub 自定义工作流文档[9]。

5.3 提交文件并检查发布结果

确认本地预览正常后,在博客根目录运行:

1
git status

如果提示尚未建立 Git 仓库,运行 git init -b main。已经存在仓库时,检查当前分支和历史后继续。首次使用 Git,需要设置提交姓名和邮箱:

1
2
git config user.name "你的名字"
git config user.email "你的邮箱"

将远端地址中的两个 USERNAME 都替换为自己的用户名,然后运行:

1
2
3
4
git remote add origin https://github.com/USERNAME/USERNAME.github.io.git
git add .github .gitignore .nvmrc _config.yml _config.redefine.yml package.json package-lock.json scaffolds source
git commit -m "Create personal blog"
git push -u origin main

首次推送需要完成 GitHub 身份验证。按照 GitHub 的 Git 设置说明[5]配置 HTTPS 或 SSH 登录。已有 origin 时,使用 git remote -v 检查地址。

回到 GitHub 仓库,打开 Actions → Pages,选择最新运行。等待 build 和 deploy 都成功,再访问 https://USERNAME.github.io/。核对首页、文章和图片,最后确认导航入口可以使用。

5.4 发布后续修改

编辑文章或配置后,运行 npx hexo clean 和 npx hexo generate,并完成本地预览。随后查看 git status,添加本次修改的具体文件,提交并推送。

例如,更新第一篇文章及其图片:

1
2
3
git add source/_posts/first-post.md source/images/posts/first-post
git commit -m "Update first post"
git push origin main

每次推送都会触发 Pages 工作流。部署成功后,刷新公开文章检查更新内容。

6. 绑定自己的域名(可选)

6.1 验证域名并填写主地址

没有独立域名时,继续使用 USERNAME.github.io。需要独立域名时,购买自己可以管理 DNS(域名解析)的域名,例如 example.com。

  1. 打开个人 GitHub 账号的 Settings → Pages → Add a domain。
  2. 填写自己的域名。
  3. 在域名注册商的 DNS 管理页面,添加 GitHub 显示的 TXT 记录。
  4. 返回 GitHub 完成验证,并保留 TXT 记录。
  5. 打开博客仓库的 Settings → Pages。
  6. 在 Custom domain 填写 example.com 并保存。

TXT 的名称和值使用自己账号页面提供的内容。操作位置参见 GitHub 域名验证说明[10]。

6.2 添加 DNS 记录

在注册商的 DNS 管理页面,为根域名添加以下四条 A 记录。主机名通常填写 @:

1
2
3
4
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

需要同时使用 www.example.com 时,增加一条 CNAME 记录:主机名填写 www,目标填写 USERNAME.github.io。目标填写域名即可。

检查相同主机名是否存在冲突记录,保留域名验证的 TXT。地址与记录规则参见 GitHub 自定义域名说明[11]。

6.3 更新配置并启用 HTTPS

将 _config.yml 的 url 和 _config.redefine.yml 的 info.url 改成 https://example.com。重新生成、提交并发布网站。

返回仓库 Settings → Pages,确认域名检查通过。等待证书可用后,勾选 Enforce HTTPS。证书检查方法参见 GitHub HTTPS 说明[12]。

在浏览器分别打开主域名、www 地址和原来的 GitHub 地址。主域名应打开博客,辅助地址应跳转到主域名。继续打开一篇文章,确认跳转后仍然显示对应正文。

7. 添加站点地图与评论(可选)

7.1 提交站点地图

安装站点地图生成器:

1
npm install --save-exact hexo-generator-sitemap@3.0.1

重新生成后,检查 public/sitemap.xml,其中的网址应使用当前公开域名。在 source/robots.txt 中填写:

1
2
3
User-agent: *
Allow: /
Sitemap: https://example.com/sitemap.xml

没有独立域名时,把地址改为 https://USERNAME.github.io/sitemap.xml。将依赖、锁文件和 robots.txt 一起提交。

在 Google Search Console 和 Bing Webmaster Tools 添加网站,完成所有权验证,再提交站点地图。收录情况使用网址检查工具查看。站点地图帮助搜索引擎发现网页,收录时间和排名仍由搜索引擎决定。Google 官方说明[13]介绍了提交方法。

7.2 配置 Giscus 评论

Giscus 使用 GitHub Discussions 保存评论。准备一个公开仓库,在 Settings → General → Features 启用 Discussions,然后安装 Giscus 应用。

打开 Giscus 配置页面[14],填写评论仓库、选择讨论分类和页面关联方式。将生成的 repo、repo_id、category 和 category_id 填入 _config.redefine.yml 的 Giscus 配置,并启用相应评论选项。

重新发布后,打开文章底部检查评论入口。博客源码使用私有仓库时,评论可以使用另一个符合 Giscus 条件的公开仓库。

8. 接入 Notion 写作与发布(进阶)

8.1 确认接入条件

Notion(在线文档工具)可以保存文章、照片和设置。自动发布还需要一个 Notion-Hexo 同步程序:读取指定内容,生成 Markdown,保存附件,并调用网站发布工作流。

开始本节前,需要取得并安装适合自己博客的同步程序。本站使用自定义程序,目前没有公开发布独立安装包。本节提供数据库、授权、配置和验收方法,供接入时使用。下文的 notion:* 命令属于这套程序,使用前检查自己的 package.json 是否包含对应命令。

一套完整的接入应具备以下能力:

  • 按“草稿”和“发布”控制公开内容。
  • 将 Notion 正文转换为 Hexo 可使用的 Markdown。
  • 保存上传的图片和附件,生成固定的网站地址。
  • 保存文章对应关系,更新后继续使用原网址。
  • 提交 GitHub、生成网站并执行部署。
  • 核验公开网页,再回写“已发布”或错误状态。

仅管理文章时,选择支持文章的同步程序即可。动态、固定页面和网站设置,还需要程序分别支持对应内容。本节的四个数据库用于这些功能齐全的接入。

8.2 建立管理页面与数据库

在 Notion 新建普通页面,命名为“博客管理”。在页面中输入 /database,选择表格数据库,创建“博客文章”。每条记录对应一篇文章,打开记录后才能编辑完整正文。

点击表格列名修改属性,点击列末尾的 + 添加属性。使用本站同步程序时,文章数据库按下表设置:

属性名称 Notion 类型 用途
标题 标题 文章名称;将原有名称列改名
发布状态 选择 控制写作与发布
发布日期 日期 文章的公开日期
摘要 文本 文章介绍
分类、标签 多选 内容分组;分别建立两项属性
封面 文件与媒体 保存封面资料
文章链接 URL 由程序填写公开网址

“发布状态”采用“选择”类型,建立“草稿”“发布”“已发布”“发布失败”“下线”“已下线”和“下线失败”选项。不同类型的“状态”属性,需要同步程序另外支持。

需要动态、页面和设置时,继续创建三个数据库。使用本站程序时,属性名称和类型如下:

数据库 属性与类型
博客动态 标题:标题;发布状态:选择;发布日期:日期;标签:多选;照片、分享封面、音乐封面、音频、头像:文件与媒体;分享链接、音乐链接、动态链接:URL;分享标题、分享说明、歌曲、歌手、作者:文本
网站页面 标题:标题;发布状态、页面:选择;摘要:文本;页面链接:URL
网站设置 设置项:标题;分组、发布状态:选择;内容:文本;链接:URL

页面与设置的发布选项使用“草稿”“发布”“已发布”和“发布失败”。本站页面类型使用“关于”“近况”和“未找到页面”,分别对应 /about/、/now/ 和 /404.html。

其他同步程序的属性要求,以其文档为准。隐藏表格列可以简化列表,属性仍可在内容页面编辑。建立“全部内容”“写作进度”“待发布草稿”和“同步异常”视图,可以分别查看内容和发布情况。

8.3 创建内部连接并授权

内部连接允许自动任务访问指定 Notion 页面。使用工作区所有者账号,按 Notion 内部连接文档[15]操作:

  1. 打开 Notion Developer portal(开发者管理页面)。
  2. 在 Build → Internal connections 创建连接。
  3. 填写连接名称,例如“博客自动发布”,选择自己的工作区。
  4. 创建后打开 Configuration,取得 API token(连接密钥)。
  5. 开启读取、插入和更新内容权限,用于读取正文、导入内容和更新发布状态。
  6. 在 Content access → Edit access 选择“博客管理”。

也可以打开“博客管理”,通过右上角 ••• → Connections → Add connection 添加连接。授权父页面后,其子页面继承访问权限。使用其他页面中的关联数据库时,还要授权原数据库。

密钥保存到 GitHub Secrets 或本地忽略文件中。数据库 ID、页面地址和密钥分别管理。

8.4 填写页面、数据库和数据源标识

Notion 的 Database(数据库)组织视图,Data source(数据源)保存属性结构。两者具有各自的 ID(标识符)。同步程序查询文章时,需要使用正确的数据源 ID。Notion 数据库说明[16]介绍了两者关系。

通过“复制链接”取得父页面和数据库地址。地址中的页面或数据库标识,可用于对应配置;查询参数 v 表示视图,填写标识时使用目标页面或数据库本身的 ID。

取得数据源 ID 时,可调用 Notion 的读取数据库 API。以下命令以已经设置 NOTION_TOKEN 和 BLOG_DATABASE_ID 环境变量为前提:

1
2
3
4
curl --fail-with-body \
"https://api.notion.com/v1/databases/$BLOG_DATABASE_ID" \
-H "Authorization: Bearer $NOTION_TOKEN" \
-H "Notion-Version: 2026-03-11"

在返回内容的 data_sources 中,找到目标数据源的 id。每个数据库分别查询,记录数据库 ID 与数据源 ID。连接没有权限时,检查上一节的页面授权。[16][17]

本站同步程序的配置文件为 notion/config.json,结构如下。全部占位文字都需要替换:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"parentPageId": "自己的博客管理页面ID",
"databaseId": "自己的文章数据库ID",
"dataSourceId": "自己的文章数据源ID",
"siteUrl": "https://example.com",
"intervalMinutes": 5,
"moments": {
"databaseId": "自己的动态数据库ID",
"dataSourceId": "自己的动态数据源ID"
},
"pages": {
"databaseId": "自己的页面数据库ID",
"dataSourceId": "自己的页面数据源ID"
},
"settings": {
"databaseId": "自己的设置数据库ID",
"dataSourceId": "自己的设置数据源ID"
}
}

siteUrl 使用自己的公开地址,结尾不添加斜线。首次接入还需要初始化文章和页面对应记录,以及设置项目与程序字段的对应记录。复用程序时,由初始化步骤生成自己的记录,保留迁移后形成的对应关系。

本站使用 notion/sync-state.json 保存文章关系,notion/content-state.json 保存动态和页面关系。notion/site-settings-state.json 将每条设置对应到程序字段;notion/site-settings.json 保存已经发布的设置值。创建新数据库后,这些记录需要重新初始化。

8.5 配置 GitHub 自动任务

同步程序还需遵守 Notion API 的请求频率与请求体限制,并处理分页、重试和授权错误。API 的官方限制与本站对单个附件设置的处理阈值是不同概念,不能互相代替。[18]

确认同步程序、依赖、初始化记录和工作流已经安装,再打开博客仓库的 Settings → Secrets and variables → Actions:

  1. 在 Secrets 中点击“New repository secret”。
  2. 名称填写 NOTION_TOKEN,内容粘贴自己的连接密钥。
  3. 在 Variables 中创建 NOTION_SYNC_ENABLED,值填写 true。
  4. 确认 Pages 发布源继续使用 GitHub Actions。
  5. 打开 Actions → Notion Sync,点击“Run workflow”。
  6. 选择 main 分支,运行并查看各步骤结果。

NOTION_SYNC_ENABLED 是本站工作流读取的变量,使用其他程序时按其要求配置。计划运行间隔由工作流的 schedule 决定;修改配置文件中的分钟数,还需要修改对应计划。

同步任务要有 contents: write 权限才能提交生成的内容。部署任务使用 Pages 权限。通过 GITHUB_TOKEN 提交的内容通常不会再次触发推送工作流,因此同步工作流应明确调用部署任务。[19][9]

本站通过 .github/workflows/notion-sync.yml 调用可复用的 Pages 工作流。第 5 节展示的是基础发布文件;接入时需要采用同步程序配套的完整工作流。

8.6 迁移内容并验证首次发布

已有文章迁移前,保存一份包含 Markdown 和原图的备份,并确认当前网站可以访问。使用同步程序的导入功能,把文章正文、标题、日期、标签、分类和封面导入 Notion。

本站程序提供以下命令,执行前需要完成上一节的安装与初始化:

1
2
3
4
npm run notion:import
npm run notion:sync
npm run verify
npm run notion:check

本地执行时,在已忽略的 .notion-local/.env 中填写 NOTION_TOKEN=自己的连接密钥。导入后,逐篇检查正文、图片、日期和公开地址。保留迁移前的网址,可以继续使用已有书签和搜索结果。

首次验证可以发布一篇自己已经写好的文章。运行同步任务后,确认 GitHub 已生成文章与附件、网站部署成功、公开正文正确,并且 Notion 状态为“已发布”。文章、动态、页面和设置分别完成对应检查后,即可使用 Notion 管理日常内容。

9. 在 Notion 中写作和修改网站

9.1 发布博客文章

完成接入后,按以下步骤写作:

  1. 打开“博客管理 → 博客文章”,点击“新建”。
  2. 把“发布状态”设为“草稿”。
  3. 填写标题、摘要和发布日期,按主题选择分类与标签。
  4. 打开记录,在属性下面编写正文。
  5. 输入 /,可以选择标题、列表、引用、图片或代码。
  6. 需要封面时,点击页面顶部的“添加封面”。
  7. 检查完成后,将状态改成“发布”。
  8. 等待“已发布”,打开“文章链接”核对网页。

分类最多选择一个,是本站程序的要求。封面可以省略。图片可以上传或拖入正文。未来日期等待到指定日期后的同步任务。

Notion 会自动保存草稿。选择“发布”后,GitHub 自动任务读取内容并部署,电脑可以关闭。网站内容通过博客网址查看,Notion 页面的共享权限单独管理。

9.2 发布动态、照片、链接和音乐

在“博客动态”点击“新建”,选择“草稿”,填写发布日期并编写正文。本站程序使用日期生成 Notion 标题,网站中的动态显示正文与日期。

  • 照片:在“照片”属性上传,每条最多 9 张;拖动文件调整顺序。
  • 网页:填写“分享链接”“分享标题”和“分享说明”,按需上传“分享封面”。
  • 音乐:填写网易云单曲的“音乐链接”,按需补充“歌曲”“歌手”和“音乐封面”。
  • 自己的音频:在“音频”属性上传文件,网站由读者点击播放。

照片文件名称不会显示在网站。需要说明时,在动态正文中填写。网站按数量排列照片,点击后可以浏览当前动态的大图。外部歌曲能否播放,取决于平台提供的音频资源。

完成后选择“发布”,等待“已发布”,打开“动态链接”检查正文和附件。这些显示效果需要博客的动态页面程序支持。

9.3 修改固定页面与网站设置

修改“关于”等页面时,打开“网站页面”中的已有记录,选择“草稿”,编辑正文,检查后选择“发布”。保留“页面”类型,程序据此确定目标网址。

首页、归档、标签和分类由网站生成。首页介绍通过设置修改,分类和标签列表由文章属性生成。新增页面网址、图片布局和交互功能,需要网站程序支持。

网站设置要事先建立“设置记录—程序字段—显示位置”的关系。以“首页大标题”为例,记录对应 homeTitle,构建程序再把这个值写入首页标题。建立关系后,才能通过 Notion 修改。

日常修改时,在“网站设置”找到已有项目,把状态改为“草稿”。在“内容”属性填写文字;社交账号在“链接”属性填写 HTTPS 地址。完成后选择“发布”,等待“已发布”并检查网站。

例如,修改“首页轮播文字”时,每行填写一句话。设置记录的正文可以用于备注,公开显示内容读取属性。本站已连接 22 个设置项目,涵盖网站信息、首页介绍、个人介绍、导航、社交入口、页脚和动态提示。

9.4 更新、下线和检查状态

修改已经公开的内容前,选择“草稿”,网站保留此前版本。完成后重新选择“发布”。保持“已发布”状态直接编辑时,本站程序会在后续同步中提交更新。

需要移除文章或动态时,选择“下线”,等待“已下线”。文章原地址应返回 HTTP(网页访问协议)404,动态应从列表消失。完成核验后,再决定是否删除 Notion 记录。需要恢复时,在保留的记录中重新选择“发布”。

本站自动任务计划每隔 5 分钟检查内容更新。GitHub 可能延迟执行,构建和部署也需要时间。需要立即提交处理时,在 Actions → Notion Sync → Run workflow 选择 main 并运行。状态显示“发布失败”时,查看最早失败步骤,修改对应内容后重新提交。[20]

草稿保存在 Notion。成功同步后,公开内容与附件进入 GitHub。本地目录通过 git pull 取得生成文件。已经交给 Notion 管理的内容,日常统一在 Notion 编辑。

10. 日常维护与问题检查

10.1 保存配置并维护依赖

_config.yml 管理网站基础信息,_config.redefine.yml 管理主题,.github/workflows/ 管理发布任务。文章和图片保存在 source/,这些文件与 package-lock.json 一起提交。

重新下载项目后,在根目录执行 npm ci,再生成和预览网站。主题升级前,保存配置;升级后比较自己的 _config.redefine.yml 与新版本配置,补充新增项目。

音乐播放器、天气和动态属于额外功能。采用此类功能时,需要安装对应程序和资源,并检查电脑、手机上的显示与操作。

10.2 本地命令或构建失败

确认终端位于包含 package.json 的目录,检查 node --version,再运行 npm ci。通过 npx hexo 调用项目中的 Hexo。

查看终端最早出现的错误。YAML 错误检查缩进与重复项目,主题错误检查安装与 theme: redefine。修正后重新生成,并确认命令成功结束。

10.3 图片、日期或网址异常

图片空白时,检查 source/images/ 中的文件是否存在、地址大小写是否一致,以及图片是否已经提交。生成后,在 public/images/ 检查对应文件。

日期异常时,检查 _config.yml 的 timezone 和文章 date。已经公开的文章保留原日期与固定网址。修改后检查网页日期及生成目录,确认两者符合预期。

10.4 部署、域名或 Notion 同步失败

网站显示旧内容时,检查最新 Actions 运行、部署时间和 Pages 地址。域名错误按第 6 节核对 DNS、证书和主域名。

Notion 连接错误时,检查密钥、页面授权、数据库及数据源标识。属性错误时,检查属性名称和类型。附件错误时,检查格式、大小和上传结果。本站同步程序的单个附件上限为 25 MB,Notion 账户的上传限制以界面提示为准。

同步与部署都成功后,仍需打开文章、动态或设置对应位置检查。Notion 的“已发布”应在公开网页核验通过后,由程序填写。

11. 开始写下自己的内容

网站准备好后,可以从一篇学习笔记、一段生活记录或一个作品介绍开始。写好内容,完成发布,再打开公开网页读一遍。随着文章逐渐增加,这个网站会形成属于你自己的记录。

日常维护也可以成为写作习惯的一部分。保存文章和图片,留意发布结果,定期检查网站中的链接。愿这份教程帮助你建立自己的博客,也让那些值得保存的想法,有一个能够长久访问的地方。

参考文献

[1] Hexo. Documentation — Installation[EB/OL].

[2] Theme Redefine. 快速开始[EB/OL].

[3] GitHub. Quickstart for GitHub Pages[EB/OL].

[4] Node.js. Download Node.js[EB/OL].

[5] GitHub. Set up Git[EB/OL].

[6] Hexo. Setup[EB/OL].

[7] Hexo. Configuration[EB/OL].

[8] Hexo. Writing[EB/OL].

[9] GitHub. Using custom workflows with GitHub Pages[EB/OL].

[10] GitHub. Verifying your custom domain for GitHub Pages[EB/OL].

[11] GitHub. Managing a custom domain for your GitHub Pages site[EB/OL].

[12] GitHub. Securing your GitHub Pages site with HTTPS[EB/OL].

[13] Google Search Central. Build and submit a sitemap[EB/OL].

[14] giscus. giscus[EB/OL].

[15] Notion. Create an internal Notion connection[EB/OL].

[16] Notion. Working with databases[EB/OL].

[17] Notion. Versioning[EB/OL].

[18] Notion. Request limits[EB/OL].

[19] GitHub. Triggering a workflow[EB/OL].

[20] GitHub. Events that trigger workflows — schedule[EB/OL].

评论

评论由 GitHub Giscus 提供。若当前网络无法加载,可 前往 GitHub Discussions 查看或参与讨论。