静态博客搭建

博客搭建

环境准备

Git 安装

下载网址 Git
打开命令提示符(CMD)验证安装版本:

1	git --version

Node.js 安装

下载网址 Node.js — Node.js 版本，找到需要下载的对应版本
打开命令提示符(CMD)验证安装版本:

node -v

给标准包管理器 npm 换源:

1	npm config set registry https://registry.npmmirror.com

Hexo 安装

Hexo 官网

打开安装好的 Git-Bash 运行，(Git-Bash 中用右键鼠标进行复制粘贴 )

npm install -g hexo-cli
# 安装指定版本hexo
npm install -g hexo-cli@版本号
e.g.
npm install -g hexo-cli@4.3.0

安装结束后，运行

hexo -v

验证安装是否成功

GitHub 部署

打开 Git-Bash，运行

git config --global user.name <你的用户名>
git config --global user.email <你的邮箱>

e.g. 用户名和邮箱自己随便写，是用来推送的用户名和邮箱
git config --global user.name Wenqi
git config --global user.email wq.shang.cn@gmail.com

运行 git config -l 检查是否配置成功

接着运行

ssh-keygen -t rsa -C <你的邮箱>
# ssh-keygen     SSH 密钥生成工具，用来生成一对密钥：公钥和私钥
# -t rsa         -t = type，rsa表示使用RSA加密算法
# -C <你的邮箱>   -C = comment(注释)，通常写邮箱或用户名，这个注释不参与加密，只是标识用途
# 如果只写 ssh-keygen 则后面默认使用RSA加密算法
e.g.
ssh-keygen -t rsa -C wq.shang.cn@gmail.com

一直按 Enter 键就可以了

密钥的默认位置在 C:\Users\用户名 文件夹下，需显示隐藏的项目，找到 .ssh 文件夹，里面有两个 id_rsa 文件，一个是公钥，一个是私钥

密钥用于此电脑连接至 GitHub

注：如果之前搭梯子生成过密钥，即 .ssh 文件夹，里面已经有两个 id_rsa 文件了，就不用再生成了

密钥生成之后，用 VSCode 或记事本打开公钥文件，全选复制里面的内容

然后点右上角头像 > Settings > SSH and GPG keys > New SSH key

Title 随便起名，Key Type 默认，Key 的内容为公钥文件里的内容，之后点 Add SSH key

运行以下代码测试连接

1	ssh -T git@github.com

由于第一次连接，需要输入 yes 确认连接

新建 Hexo 项目

新建并进入一个新文件夹，右键鼠标Open Git Bash here，运行

hexo init <folder>
# 进入刚创建好的文件夹
cd <folder>
# 安装依赖
npm install

e.g.
hexo init Wenqi_Blog
cd Wenqi_Blog
npm install

Hexo 项目文件夹结构如下

Wenqi_Blog/
├── _config.yml        # 全局网站配置文件，定义站点标题、URL、目录结构等
├── package.json       # 项目依赖与脚本管理文件
├── scaffolds/         # 模板文件夹，存放创建文章、页面时使用的模板（archetypes）
├── source/            # 网站内容文件夹
│   ├── _drafts/       # 草稿文件夹，保存未发布的文章
│   └── _posts/        # 文章文件夹，存放发布后的博客文章
├── themes/            # 主题文件夹，可存放多个主题，激活时在 _config.yml 中指定
└── public/            # 生成的静态文件目录（每次执行 hexo generate 时更新）

详细说明：

_config.yml

存放全局配置，例如站点信息、URL规则、分页设置等，是 Hexo 的核心配置文件
package.json

用于管理项目的依赖项和脚本命令，方便扩展和自动化构建
scaffolds/

内涵默认的文章和页面模板，可以根据需要修改或新增自定义模板
source/

所有博客内容的存放地，按照用途划分为草稿（drafts）和正式文章（posts）文件夹，也可以在该文件夹中创建图片、附件等资源文件夹
themes/

存放博客主题，每个主题包含独立的布局、样式及部分配置文件

安装主题后需在_config.yml中指定启用的主题名称
public/

每次生成静态站点文件时输出到此目录下，实际部署的即为该文件夹内容

若需预览效果，在Wenqi_Blog文件夹中，右击鼠标打开 GitBash 运行hexo s查看生成后的页面

然后安装一些优化插件

1
2
3

# SEO 优化
npm install hexo-generator-sitemap --save # 下载站点地图，方便搜索引擎收录
npm install hexo-generator-feed --save # 方便别人订阅你的博客

配置 Hexo 可参考官方配置文档

# 生成一个静态文件
hexo g 
# 启动服务器。默认情况下，访问网址为：http://localhost:4000/
hexo s 
# 这两句常用来测试

在博客根目录下打开 GitBash ，输入touch .gitignore，复制下面内容

（注意在博客根目录下创建.txt文件命名为.gitignore <— 这种方法容易出错，容易找不到.gitignore文件，就干脆别用)

# dependencies
node_modules/

# hexo build output
public/
.deploy_git/

# hexo / search db
db.json

# system files
.DS_Store

因为部署是通过 GitHub Actions 自动部署，无需本地部署，只需要直接提交其他文件就行了，上面那些文件不用提交

可以在 GitBash 中输入cat .gitignore检查一下

Hexo 主题安装

可参考

注意要把博客源码提交到私人仓库并用GitHub Actions自动部署的话

删除主题文件夹里的.git

执行rm -rf themes/butterfly/.git
每次更新主题的话记得删除.git避免报错

托管到 GitHub

创建一个私有仓库，用于储存博客源代码
创建一个公开仓库，用于显示博客
点击右上角头像 > settings > Developer settings > Person access tokens > Tokens (classic) > Generate new token (classic)
1. Expiration(到期时间) > No Expiration
2. 勾选上 repo 和 workflow
3. 注意所有生成的令牌都不要删，以防误删哪个，避免麻烦
复制这个令牌
在私有仓库(存源码的仓库)下 > settings > Secrets and variables > Actions

名字随便起，Secret 中粘贴刚才复制到令牌，

注意，Secret的名字用大写字母，可以有下划线
返回私有仓库Code界面，并选择SSH协议，可以看到一些提示的指令

#…or create a new repository on the command line
echo "# BlogSource" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:Venqi-S/BlogSource.git
git push -u origin main

#…or push an existing repository from the command line
git remote add origin git@github.com:Venqi-S/BlogSource.git
git branch -M main
git push -u origin main

在Wenqi_Blog文件夹下，打开 GitBash
1. 运行git init
2. 运行git remote add origin git@github.com:Venqi-S/BlogSource.git进行远程连接
3. 运行git branch -M main将当前分支改为main，也可以是master
在.github文件夹下创建workflows文件夹，在workflows文件夹下创建deploy.yml文件
使用 VSCode 打开Wenqi_Blog文件夹，编辑.github\workflows\deploy.yml文件将下面代码复制进去

# 工作流名称：显示在 GitHub Actions 页面
name: Deploy Hexo Blog

# 触发条件：当向指定分支 push 时触发
on:
  push:
    branches:
      - main        # 【可能需要改】如果你的源码分支是 master，这里要改成 master

jobs:
  deploy:
    # 运行环境：使用 GitHub 提供的 Ubuntu
    runs-on: ubuntu-latest

    steps:
      # Step 1：检出源码仓库（BlogSource）
      - name: Checkout BlogSource
        uses: actions/checkout@v4
        # 默认会把当前仓库（BlogSource）的代码拉到 runner 中

      # Step 2：安装 Node.js
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20     # 【不建议改】推荐用 LTS（18 / 20），不要用 24，这里的node版本与你下载的版本无关，所以不用改
          cache: npm           # 启用 npm 缓存，加快 CI 速度

      # Step 3：安装依赖
      - name: Install dependencies
        run: npm ci
        # 使用 npm ci 而不是 npm install：
        # - 更快
        # - 严格按照 package-lock.json
        # - 更适合 CI 环境

      # Step 4：构建 Hexo（生成 public 目录）
      - name: Build Hexo
        run: |
          npx hexo clean       # 清理缓存和旧的生成文件
          npx hexo generate    # 生成静态文件到 ./public

      # Step 5：部署 public 到 公开仓库
      - name: Deploy to 公开仓库
        uses: peaceiris/actions-gh-pages@v4
        with:
          keep_files: false
          # false = 目标仓库内容将完全以 public 为准
          # 【推荐保持 false】避免删除文章后网页还残留

          personal_token: ${{ secrets.刚才起的Secret的名字 }}
          # 【可能需要改】
          # secret 名必须和 BlogSource 仓库里设置的一致

          external_repository: GitHub用户名/目标仓库名
          # 【可能需要改】
          # 格式：GitHub用户名/目标仓库名
          # 这是你的“博客展示仓库（公开仓库）”

          publish_branch: main
          # 【可能需要改】
          # 如果是 master，就要改成 master

          publish_dir: ./public
          # 【一般不用改】
          # Hexo 默认生成目录就是 public（注意大小写）
		 # GitHub 给我写的

在博客根目录下，打开GitBash，依次输入

#第一次输入
git add .
git commit -m "first commit"
git push -u origin main

#以后提交就直接输入
git add .
git commit -m "提交时的备注"
git push

回到公开仓库刷新一下，可以看到本地博客文件夹里的pubilc文件夹的内容被推送上来

Settings > Pages > Branch 选择main/(root) > save

自定义域名访问博客

购买一个域名 Cheap Domain Names & Web Hosting Starting at $0.99!

只要一个 whois 就行，别的付费项目不需要
进入随时随地连接、保护和构建 | Cloudflare > 添加域 > 输入刚才买的域名其他保持默认选择 > 点击继续
选则免费的，点击继续
全部删除，点击继续，然后选择确认

进入到下面的界面
返回 NameSilo > 进入个人主页 > 点击manage > 按顺序点击
然后将所有的 NameSever 都删除，把第四步出现的两个 Cloudflare 都粘贴进去，点击submit
返回 Cloudflare > 点击我已更新名称服务器 > 刷新一下界面等待成功（大约半个多小时）> 点击刚才添加的域名 > 选择左侧 DNS > 记录
打开GitHub 博客的公开仓库 > Settings > Pages > Custom domain > Learn more about configuring custom domains > Manage a custom domain > 找到第五条的八个 IP 地址
返回 Cloudflare 添加四个 A 记录和四个 AAAA 记录，名称都写@，且先关闭自动代理状态（方便 GitHub 识别域名的解析），其他保持默认

把八条解析记录都添加进去

在进行下一步时请看最后的“注2”，将其中的代码加入到.github\workflows\deploy.yml 文件中去，然后和下一步一起 push 上去
在本地文件_config.yml中修改 url 为https://自己的域名，然后上传至 GitHub

add > commit > push
返回 GitHub 在 Custom domain 填写自己买的域名 > 点击 save
最后在 Cloudflare 中把每个记录启用代理，然后稍等一会，就能用自己的新域名访问博客了

注1：

出现图片中的情况是因为

网站裸域名 (Apex domain) wqblog.xyz 已经正确指向 GitHub Pages（A/AAAA 记录均已配置），所以 wqblog.xyz 可以正常访问。但 www.wqblog.xyz 在 DNS 中是一个独立的子域名，目前没有配置任何记录，导致 GitHub Pages 提示 www.wqblog.xyz is improperly configured。解决方法是在 DNS 中新增一条 CNAME 记录，将 www 指向 venqi-s.github.io，使 www.wqblog.xyz 与裸域名同时生效，并由 GitHub Pages 自动处理 HTTPS 和跳转。(ChatGPT 说的)

所以返回 Cloudflare ，再添加一个记录

类型 CNAME，名称 www ，内容 venqi-s.github.io 上图红框的内容，其他默认

稍等一会，返回 GitHub 刷新一下就没有警告了

注2：现在每次提交都需要重新在 pages 页面重新输入域名。因为每次部署都会“覆盖 GitHub Pages 的发布分支”，把 CNAME 文件删掉了，GitHub Pages 就会忘记你的自定义域名，所以每次 push 后都要重新填域名

解决方法：

在 .github\workflows\deploy.yml 文件中加入下面一段

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v4
  with:
    personal_token: ${{ secrets.刚才起的Secret的名字 }} 
    # secret 名必须和 BlogSource 仓库里设置的一致
    external_repository: GitHub用户名/目标仓库名
    publish_branch: main
    publish_dir: ./public
    cname: 购买的域名

然后在 source 文件夹内新建一个 CNAME 文件内容写购买的域名如 wqblog.xyz

作用：

每次部署都会自动写入 CNAME
就算发布分支被完全覆盖，域名也不会丢