神觉晓

@shenjuexiao

神觉晓

hexo-theme-next add Giscus

hexo-theme-next 添加 Giscus

内容来源

在 NexT 主题中为 Hexo 博客添加 Giscus 评论系统,主要有这几个步骤:准备好 GitHub 仓库、安装 NexT 专用的 Giscus 插件,然后在主题配置文件中填入从 Giscus 官网获取的关键信息。

📝 第一步:准备工作

在开始配置前,需要先完成三项必要的 GitHub 设置,这些是所有后续操作的基础:

  1. 创建一个公开的 GitHub 仓库:Giscus 要求评论数据存放在公开仓库中。你可以用现有的博客仓库,或者为评论单独新建一个仓库。

  2. 启用仓库的 Discussions 功能:进入仓库的 Settings -> General,在 Features 部分找到并勾选 Discussions

  3. 安装 Giscus App:访问 GitHub Apps - giscus,点击安装,并选择你刚刚准备好(已公开且开启 Discussions)的仓库。

Giscus GitHub Apps giscus

⚙️ 第二步:安装与配置

1. 安装 NexT 专用插件

由于 NexT 主题本身不直接支持 Giscus,需要安装一个社区插件来集成。在博客根目录下执行以下命令:

1
npm install hexo-next-giscus --save

这个插件会负责在页面中注入 Giscus 所需的代码,并让配置能和 NexT 主题很好地结合起来。

2. 获取配置参数

安装完插件后,访问 Giscus 官网,它会引导你完成配置并生成一段 <script> 代码。

主要需要填写的几个关键信息是:

  • 仓库你的GitHub用户名/评论仓库名
  • 页面 ↔️ discussion 映射关系:对于 Hexo 博客,通常推荐选择 pathname,这样每篇文章的评论会和其 URL 路径绑定。
  • Discussion 分类:选择一个已有的分类,如 GeneralAnnouncements。建议选择 Announcements,这样新的 discussion 只能由维护者或 Giscus 创建,可以避免混乱。

Giscus giscus.app/zh-CN

配置好后,在页面最下方复制生成的代码,我们只需要从中提取几个以 data- 开头的参数值。

3. 将参数填入 NexT 配置文件

打开主题配置文件 themes/next/_config.yml(或者根目录的 _config.next.yml),在文件末尾添加或修改以下 giscus 配置块。

将上一步从 Giscus 官网复制下来的参数(如 data-repo, data-repo-id 等)对应的值填写进去,注意不要保留 data- 前缀和引号

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 在 themes/next/_config.yml 文件末尾添加
giscus:
enable: true
# 用户名/仓库名,对应 data-repo
repo: 用户名/仓库名
# 仓库 ID,对应 data-repo-id
repo_id: 仓库 ID
# 选择的分类,对应 data-category
category: Announcements
# 分类ID,对应 data-category-id
category_id: 你的分类 ID
# 推荐用页面路径匹配,对应 data-mapping
mapping: pathname
# 开启表情回应
reactions_enabled: 1
emit_metadata: 0
# 评论框位置
input_position: bottom
# 建议使用自动适配主题
theme: preferred_color_scheme
# 语言设置
lang: zh-CN
# 懒加载,提升性能
loading: lazy

🚀 第三步:部署与测试

最后,重新生成并部署你的博客,就可以看到效果了:

1
hexo clean && hexo generate && hexo deploy

或者直接使用:

1
hexo server

部署成功后,打开任意一篇文章滑到底部,就能看到 Giscus 评论区了。如果页面没有显示,可以检查一下博客是否已经成功部署到线上。

Giscus shenjuexiao.com

Typecho-CF 安装部署

内容来源

基于 Typecho 完整重写的现代博客系统,运行在 Astro + Cloudflare Workers + D1 之上。保留 Typecho 数据库表结构,支持从 PHP 版 Typecho 直接迁移数据。

前置要求

  • Node.js 18+
  • pnpm(npm install -g pnpm)
  • Wrangler CLI(npm install -g wrangler)
  • Cloudflare 帐号

本地开发

1
2
3
4
5
6
7
8
9
# 克隆并安装依赖
git clone https://github.com/eslizn/typecho-cf.git
cd typecho-cf
pnpm install

# 启动开发服务器(D1 + R2 由 wrangler 自动模拟)
pnpm run dev
# 访问 http://localhost:4321
# 首次访问自动跳转安装向导

Typecho-CF pnpm run dev

Error: Failed to load url path

Typecho-CF_Failed_to_Load_URL_Path

搞了半天弄不好,暂时放弃了。

记录一下,往后再折腾。

Test3

Test2

Test1

Gmeek 部署其他仓库

📦 原有: Gmeek.yml

原有 GitHub Actions ,通过 actions/upload-pages-artifact@v3actions/deploy-pages@v4 自动化部署到本仓库的虚拟机上(注:不知这样理解是否正确)。

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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
name: build Gmeek

on:
workflow_dispatch:
issues:
types: [opened, edited]
schedule:
- cron: \"0 16 * * *\"

jobs:
build:
name: Generate blog
runs-on: ubuntu-24.04
if: ${{ github.event.repository.owner.id == github.event.sender.id || github.event_name == 'schedule' }}
permissions: write-all
steps:
- name: Checkout
uses: actions/checkout@v4

- name: Setup Pages
id: pages
uses: actions/configure-pages@v4

- name: Get config.json
run: |
echo \"====== check config.josn file ======\"
cat config.json
echo \"====== check config.josn end ======\"
sudo apt-get install jq

- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: 3.8

- name: Clone source code
run: |
GMEEK_VERSION=$(jq -r \".GMEEK_VERSION\" config.json)
git clone https://github.com/Meekdai/Gmeek.git /opt/Gmeek;
cd /opt/Gmeek/
lastTag=$(git describe --tags `git rev-list --tags --max-count=1`)
if [ $GMEEK_VERSION == 'last' ]; then git checkout $lastTag; else git checkout $GMEEK_VERSION; fi;

- name: Install dependencies
run: |
pip install --upgrade pip
pip install -r /opt/Gmeek/requirements.txt

- name: Generate new html
run: |
cp -r ./* /opt/Gmeek/
cd /opt/Gmeek/
python Gmeek.py ${{ secrets.GITHUB_TOKEN }} ${{ github.repository }} --issue_number '${{ github.event.issue.number }}'
cp -a /opt/Gmeek/docs ${{ github.workspace }}
cp -a /opt/Gmeek/backup ${{ github.workspace }}
cp /opt/Gmeek/blogBase.json ${{ github.workspace }}

- name: update html
run: |
git config --local user.email \"$(jq -r \".email\" config.json)\"
git config --local user.name \"${{ github.repository_owner }}\"
git add .
git commit -a -m '🎉auto update by Gmeek action' || echo \"nothing to commit\"
git push || echo \"nothing to push\"
sleep 3

- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: 'docs/.'

deploy:
name: Deploy blog
runs-on: ubuntu-24.04
needs: build
permissions:
contents: write
pages: write
id-token: write
concurrency:
group: \"pages\"
cancel-in-progress: false
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4

🔧 .yml 修改需求

源仓库生成相关文件后,将静态页面 ./docs 下的文件推送到博客仓库分支 gh-pages 上,即网站部署在分支。

  • 源仓库: shenjuexiao/gmeek-source
  • 博客仓库: shenjuexiao/gmeek-docs
  • 工作流 Deploy 增加 docs 下静态页面部署到博客仓库 gh-pages 分支
  • 使用 peaceiris/actions-gh-pages
  • 跨仓库使用 token:${{ secrets.GMEEK_DOCS }}

❌ Error: HttpError: Not Found

Gmeek Deploy Setup Pages

注释掉本地的部署

1
2
3
4
# 不需要配置 GitHub Pages
# - name: Setup Pages
# id: pages
# uses: actions/configure-pages@v4
1
2
3
4
5
6
7
# 去掉源仓库的部署
# actions/upload-pages-artifact@v3 是专门为 GitHub Pages 设计的
# 创建特殊的 artifact,只能被 actions/deploy-pages@v4 使用
# - name: Upload artifact
# uses: actions/upload-pages-artifact@v3
# with:
# path: 'docs/.'
1
2
3
4
# 去掉源仓库的部署
# - name: Deploy to GitHub Pages
# id: deployment
# uses: actions/deploy-pages@v4

🔑 Error: Action failed with "not found deploy key for tokens"

Gmeek Deploy docs to

源仓库需要设置 token

  • 创建 GitHub 个人访问令牌 PAT Personal access tokens (classic)
    GitHub 头像,Settings -> Developer settings -> Personal access tokens -> Tokens (classic)
    新建 Token,勾选权限:repo(全部仓库读写权限)。
    复制生成的 Token(仅展示一次,丢失需重建)。
  • 仓库配置 Repository secrets
    仓库首页, Settings -> Secrets and variables -> Actions -> New repository secret
    Name:GH_TOKEN。
    Value:粘贴上面的 PAT。

✅ 修改后 gmeek-docs.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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
name: build Gmeek

on:
workflow_dispatch:
issues:
types: [opened, edited]
# schedule:
# - cron: \"0 16 * * *\"

jobs:
build:
name: Generate blog
runs-on: ubuntu-24.04
if: ${{ github.event.repository.owner.id == github.event.sender.id || github.event_name == 'schedule' }}
permissions: write-all
steps:
- name: Checkout
uses: actions/checkout@v4

- name: Get config.json
run: |
echo \"====== check config.josn file ======\"
cat config.json
echo \"====== check config.josn end ======\"
sudo apt-get install jq

- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: 3.8

- name: Clone source code
run: |
GMEEK_VERSION=$(jq -r \".GMEEK_VERSION\" config.json)
git clone https://github.com/Meekdai/Gmeek.git /opt/Gmeek;
cd /opt/Gmeek/
lastTag=$(git describe --tags `git rev-list --tags --max-count=1`)
if [ $GMEEK_VERSION == 'last' ]; then git checkout $lastTag; else git checkout $GMEEK_VERSION; fi;

- name: Install dependencies
run: |
pip install --upgrade pip
pip install -r /opt/Gmeek/requirements.txt

- name: Generate new html
run: |
cp -r ./* /opt/Gmeek/
cd /opt/Gmeek/
python Gmeek.py ${{ secrets.GITHUB_TOKEN }} ${{ github.repository }} --issue_number '${{ github.event.issue.number }}'
cp -a /opt/Gmeek/docs ${{ github.workspace }}
cp -a /opt/Gmeek/backup ${{ github.workspace }}
cp /opt/Gmeek/blogBase.json ${{ github.workspace }}

- name: update html
run: |
git config --local user.email \"$(jq -r \".email\" config.json)\"
git config --local user.name \"${{ github.repository_owner }}\"
git add .
git commit -a -m '🎉auto update by Gmeek action' || echo \"nothing to commit\"
git push || echo \"nothing to push\"
sleep 3

# 生成 HTML 后立即将 docs 文件夹上传为 artifact
- name: Upload docs artifact
uses: actions/upload-artifact@v4
with:
name: docs
path: ${{ github.workspace }}/docs
# 设置保留 1 天,节省存储空间
retention-days: 1

deploy:
name: Deploy blog
runs-on: ubuntu-24.04
needs: build
permissions:
contents: write
pages: write
id-token: write
concurrency:
group: \"pages\"
cancel-in-progress: false
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
# 先下载 build job 上传的 docs artifact,下载到 ./docs 目录
- name: Download docs artifact
uses: actions/download-artifact@v4
with:
name: docs
path: ./docs

# 新增:部署 docs 到博客仓库的gh-pages分支
- name: Deploy docs to gmeek-docs gh-pages
uses: peaceiris/actions-gh-pages@v3
with:
personal_token: ${{ secrets.GMEEK_DOCS }}
external_repository: shenjuexiao/gmeek-docs
publish_branch: gh-pages
publish_dir: ./docs
commit_message: '🚀 Deploy static pages to gh-pages'
user_name: 'github-actions[bot]'
user_email: 'github-actions[bot]@users.noreply.github.com'
keep_files: false
force_orphan: false

GitHub CNAME 的作用

内容来源

GitHub仓库里的CNAME文件,核心作用是告诉GitHub Pages服务器,当用户通过你的自定义域名(比如 www.example.com)访问时,应该展示哪个仓库的网站内容

你可以把它理解为在GitHub内部为你的域名和特定仓库建立的一个“认领”和“关联”关系。它需要在你的域名解析服务商(如阿里云、Cloudflare)设置的DNS解析配合下才能正常工作。

⚙️ 如何工作

当用户在浏览器输入你的自定义域名(如 www.example.com)并访问时,流程如下:

  1. DNS解析:用户的请求首先会去DNS服务器查询www.example.com指向哪里。你需要在DNS服务商那里添加一条 CNAME记录,将 www.example.com 指向 你的用户名.github.io。这一步把域名指向了GitHub的服务器。
  2. 请求到达GitHub:请求到达GitHub的服务器后,服务器需要知道这个请求是给哪个仓库的。
  3. 读取CNAME文件:此时,GitHub会检查所有启用了Pages的仓库,寻找根目录下名为CNAME必须大写)的文件。
  4. 匹配与响应:当GitHub在你的仓库里找到的CNAME文件内容(例如www.example.com),与用户请求的域名完全匹配时,它就知道要把这个仓库的网站内容返回给用户了。

🌐 仓库和服务商 CNAME 比较

两者的关系:分工明确的“钥匙”与“路标”。这两者缺一不可,它们共同完成从“自定义域名”到“具体 GitHub 仓库”的映射。

组成部分 作用概括 配置位置 关键点
仓库 CNAME 文件 “钥匙”:授权并告诉 GitHub,哪个域名可以访问这个仓库 仓库根目录下的 CNAME 文件 内容必须与 DNS 记录的子域名一致,且只能有一个域名
DNS CNAME 记录 “路标”:将互联网流量从你的域名指向 GitHub 服务器 域名注册商/DNS 服务商的管理后台 通常用于 www 子域名,指向<用户名>.github.io

📌 重要补充

  • 安全与唯一性:这个文件也是一种安全机制,确保只有你(仓库所有者)能决定哪个域名可以访问你的网站。如果一个域名已经被某个仓库的CNAME文件“占用”了,其他仓库就无法再使用该域名,除非你将其删除。
  • 避免使用通配符:切记不要在你的DNS服务商处为GitHub Pages设置通配符记录(如 *.example.com)。因为任何GitHub用户都可以在自己的仓库里创建一个指向你任意子域名的CNAME文件,从而可能“劫持”你的子域名来托管他们的内容。
  • 多域名支持:一个CNAME文件中只能包含一个域名。如果你想把多个域名都指向同一个网站,可以通过你的DNS服务商设置URL转发或使用其他DNS记录来实现。
  • 静态站点生成器注意事项:如果你使用Hexo、Hugo等静态站点生成器,建议将CNAME文件放在项目的源文件夹(如source目录)下。这样每次部署时,它就会被自动复制到生成的public文件夹并推送到GitHub,避免每次部署后CNAME文件丢失的问题。
  • Apex 根域名:需要注意,对于 example.com 这样的根域名(也叫 Apex 域),由于 DNS 规范限制,不能使用 CNAME 记录。你需要配置 A 记录,将其指向 GitHub 的固定 IP 地址(185.199.108.153 等四个 IP),才能实现根域名的访问。不过,这并不影响在仓库中依然需要一个内容为 example.com 的 CNAME 文件来完成授权。

Astro 安装及 GitHub Actions 自动部署

内容来源

通过 CLI 向导安装

docs.astro.build/zh-cn/install-and-setup/

我选择的是 Astro Use blog template,也可以选择其他的选项,使用模板能快速建立页面。

Astro Use blog template

1
2
# 使用 npm 创建一个新项目
npm create astro@latest

1
2
# 使用 pnpm 创建一个新项目
pnpm create astro@latest

1
2
# 使用 yarn 创建一个新项目
yarn create astro

npm create astro@latest

目录和文件

docs.astro.build/zh-cn/basics/project-structure/

Astro 采用一套约定俗成的文件夹布局来管理项目。每个 Astro 项目的根目录下都应该包括以下目录和文件:

  • src/* - 你的项目源代码(组件、页面、样式、图片等)。
  • public/* - 你的非代码、未处理的资源(字体、图标等)。
  • package.json - 项目清单。
  • astro.config.mjs - Astro 配置文件(推荐)。
  • tsconfig.json - TypeScript 配置文件(推荐)。

启动 Astro 开发服务器

docs.astro.build/zh-cn/develop-and-build/

Astro 自带了一个内置的开发服务器,它包含了项目开发所需的一切。astro dev CLI 命令将启动本地开发服务器,让你第一次看到你的新网站。

每个起始模板都预配置了一个脚本,该脚本将为你运行 astro dev。在进入你的项目目录后,使用你喜欢的包管理器运行此命令并启动 Astro 开发服务器。

1
npm run dev

1
pnpm run dev

1
yarn run dev

部署你的 Astro 站点至 GitHub Pages

docs.astro.build/zh-cn/guides/deploy/github/

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
name: Deploy to GitHub Pages

on:
# 每次推送到 `main` 分支时触发这个“工作流程”
# 如果你使用了别的分支名,请按需将 `main` 替换成你的分支名
push:
branches: [ main ]
# 允许你在 GitHub 上的 Actions 标签中手动触发此“工作流程”
workflow_dispatch:

# 允许 job 克隆 repo 并创建一个 page deployment

```yaml
permissions:
contents: read
pages: write
id-token: write

jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout your repository using git
uses: actions/checkout@v5
- name: Install, build, and upload your site
uses: withastro/action@v5
# with:
# path: . # 存储库中 Astro 项目的根位置。(可选)
# node-version: 20 # 用于构建站点的特定 Node.js 版本,默认为 20。(可选)
# package-manager: pnpm@latest # 应使用哪个 Node.js 包管理器来安装依赖项和构建站点。会根据存储库中的 lockfile 自动检测。(可选)
# build-cmd: pnpm run build # 用于构建你的网站的命令。默认运行软件包的构建脚本或任务。(可选)
# env:
# PUBLIC_POKEAPI: 'https://pokeapi.co/api/v2' # 对变量值使用单引号。(可选)

deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4

Error: Failed to create deployment (status: 404)

Astro Deploy to GitHub Pages

这个错误表明 GitHub Pages 部署失败,主要原因是 GitHub Pages 没有在仓库设置中启用。错误信息明确指出:

Ensure GitHub Pages has been enabled: https://github.com/shenjuexiao/astro/settings/pages

npm 与 npx 区别

内容来源

简单说明

npmnpxNode.js 生态里两个核心但职责不同的工具,可以用一句话来区分它们:

npm 是“包管理器”,负责安装、管理依赖;而 npx 是“包执行器”,负责运行命令,无需显式安装

表格比较

特性 npm (Node Package Manager) npx (Node Package Execute)
核心职责 管理项目的依赖包,比如安装、卸载、更新、发布包 执行某个 Node.js 包提供的命令
是否需要安装 需要。包会被下载并保存到 node_modules 或全局目录 通常不需要。它会临时下载并执行,用完即走,不污染环境
典型场景 为项目安装核心依赖(如 npm install react
运行 package.json 中定义的脚本(如 npm run build
运行一次性的脚手架工具(如 npx create-react-app my-app
快速测试不同版本的包(如 npx webpack@4.44.1 -v
执行本地包 需要通过 ./node_modules/.bin/ 路径或 npm run 命令间接运行 可以直接运行,它会自动在 node_modules/.bin/ 中查找命令

除了用法上的不同,npx 还有一个非常便利的特性:它可以临时下载并运行一个远程的 npm 包,这在测试新工具或运行一次性脚本时能帮你节省不少时间。

💡 如何选择?

一个很实用的场景是:创建 React 项目时,会先全局安装 create-react-app,再用它生成项目。有了 npx,可以直接 npx create-react-app my-app,不用全局安装,每次用的还都是最新版,非常方便。

一句话总结就是

  • 需要一个包长期使用(比如项目依赖)→ 用 npm install
  • 只是想临时跑一下某个命令或工具 → 用 npx

GitHub 图片加速对比

内容来源

🔍比较图片引用

raw.githubusercontent.comcdn.jsdelivr.net/gh

简单来说,raw.githubusercontent.com 是图片在 GitHub 上的源服务器地址,而 cdn.jsdelivr.net/gh 则是一个免费的 CDN 加速服务,它的核心作用就是为前者"提速"。

下面是它们在几个关键维度上的直接对比:

对比维度 raw.githubusercontent.com (源站) cdn.jsdelivr.net/gh (CDN)
核心作用 直接访问 GitHub 服务器上的原始文件 通过全球 CDN 节点缓存并分发文件,进行加速
访问速度 通常较慢,尤其在中国大陆地区,延迟高,加载不稳定 显著更快,利用全球边缘节点就近响应,可大幅缩短加载时间
稳定性与限制 存在请求频率限制 (Rate Limit),高并发或大量图片时可能返回 HTTP 429 错误,导致图片无法加载 通常无严格的请求限制,但有单文件 50MB 的大小限制,且仅支持公开仓库
缓存机制 缓存策略较弱,重复访问可能仍需重新下载 具备强大的缓存机制(默认缓存24小时或更久),重复访问直接从 CDN 节点读取,速度极快
URL 格式示例 https://raw.githubusercontent.com/用户名/仓库名/分支名/图片路径.png https://cdn.jsdelivr.net/gh/用户名/仓库名@分支名或版本号/图片路径.png

⚠️ 重要的潜在问题与建议

虽然 jsDelivr 优势明显,但在国内使用时需要留意一个已知风险:

国内 DNS 污染问题jsDelivr 的官方域名 cdn.jsdelivr.net 在国内曾因DNS污染导致访问失败。如果你遇到这种情况,可以考虑使用它未被污染的备用域名,例如 fastly.jsdelivr.netgcore.jsdelivr.net 作为替代方案。

💎 总结与选择建议

  • 对于个人项目、博客、官网等公开场景:强烈建议使用 cdn.jsdelivr.net/gh**。它能带来质的飞跃,让图片"秒开"不再困难,综合体验完胜直连源站。
  • raw.githubusercontent.com 的适用场景**:主要用于在 GitHub 页面上直接预览文件内容,或在你需要从服务器后台程序以编程方式获取文件原始内容时使用。
0%