Github_page

第一阶段：本地环境配置

  1. 安装核心工具：安装 Node.js 和 Git。

  2. 权限解锁：在 PowerShell 中执行 Set-ExecutionPolicy RemoteSigned 以允许运行 npm 脚本。

  3. 安装 Hexo：运行 npm install -g hexo-cli。

⚠️ 常见犯错提示：

  • 脚本禁用错误：如果你直接运行 hexo 报错“在此系统上禁止运行脚本”，记得一定要以管理员身份运行 PowerShell 并修改执行策略。

  • 版本不兼容：如果 npm install 极慢，建议使用国内镜像源（如 npm config set registry https://registry.npmmirror.com）。

第二阶段：GitHub 仓库准备

  1. 创建特殊仓库：在 GitHub 上新建一个仓库。

  2. 命名规范：仓库名必须为 你的用户名.github.io。

⚠️ 常见犯错提示：

  • 命名失误：仓库名少写了 .github.io 或者用户名拼写错误，会导致无法通过域名直接访问博客。

  • 改名遗留问题：如果你修改过 GitHub 用户名，旧的仓库名必须同步手动重命名，否则 Hexo 无法找到推送目标。

第三阶段：本地初始化与部署配置

  1. 初始化：在本地文件夹运行 hexo init 和 npm install。

  2. 安装插件：运行 npm install hexo-deployer-git --save。

  3. 配置 _config.yml：修改文件底部的 deploy 部分：

    YAML

    1
    2
    3
    4
    deploy:
      type: git
      repo: https://github.com/用户名/用户名.github.io.git
      branch: main

⚠️ 常见犯错提示：

  • YAML 格式错误：type:, repo: 等冒号后面必须有一个空格，缩进必须对齐，否则会报 Config Error。

  • 分支名称错误：GitHub 现在默认分支名是 main 而不是 master，如果填错会导致部署成功但在网页上看不到内容。

第四阶段：笔记整理与上传流程

这是你以后最常重复的步骤：

步骤 命令 说明
1. 新建 hexo new "标题" 在 source/_posts 生成 .md 文件
2. 编写 使用 VS Code 编写 建议给 C++/Java 笔记设置清晰的 tags 和 categories
3. 清理 hexo clean 必做，防止旧缓存导致页面显示异常
4. 生成 hexo g 将 Markdown 渲染成 HTML 网页
5.本地预览 hexo s 在浏览器打开 http://localhost:4000
6. 上传 hexo d 推送到 GitHub 服务器

⚠️ 常见犯错提示：

  • 网络连接重置：报错 Connection was reset 或 Failed to connect 时，检查你的 Git 代理设置。如果你没开代理软件，运行 git config --global --unset http.proxy 取消代理。

  • 图片无法显示：笔记中的图片路径如果指向你电脑本地（如 C:\Users\...），上传后博客会“碎图”。建议学习使用 PicGo 图床 或将图片放入 source/images 文件夹并使用相对路径。

  • 源码丢失：hexo d 只会上传“网页结果”，不会备份你的 .md 原稿。建议将整个博客文件夹再建立一个私有仓库备份，防止电脑宕机。

“双仓库法”

：一个公开仓库展示博客，一个私有仓库保存源码。

第一步：在 GitHub 上创建一个私有仓库

  1. 登录 GitHub，点击右上角的 + -> New repository。

  2. Repository name：建议起名为 hexo-source 或 blog-backup。

  3. Public/Private：务必选择 Private（私有），这样别人就看不到你的源码和未发布的草稿。

  4. 不要勾选 “Initialize this repository with a README”。

  5. 点击 Create repository，复制生成的仓库地址（如 https://github.com/用户名/hexo-source.git）。

第二步：配置本地 .gitignore（关键防错）

在你的本地博客根目录（my_blog）下，检查是否存在 .gitignore 文件。如果没有，新建一个。这个文件的作用是告诉 Git 哪些文件不要备份（比如几百 MB 的依赖包）。

请确保 .gitignore 中包含以下内容：

Plaintext

1
2
3
4
5
6
7
.DS_Store
Thumbs.db
db.json
*.log
node_modules/
public/
.deploy_git/

第三步：初始化 Git 并推送到私有仓库

在你的本地 my_blog 文件夹下打开终端，依次执行以下命令：

  1. 初始化 Git：

    Bash

    1
    git init

  2. 关联私有仓库：

    Bash

    1
    git remote add origin https://github.com/你的用户名/你的私有仓库名.git

  3. 提交并上传：

    Bash

    1
    2
    3
    git add .
    git commit -m "Backup hexo source code"
    git push -u origin master (或 main)

Butterfly 主题

第一步：安装主题及核心依赖

Butterfly 强依赖于 Pug 和 Stylus 渲染引擎，所以你必须安装它们才能正常显示网页。

  1. 在博客根目录打开终端，运行安装命令：

    Bash

    1
    npm install hexo-theme-butterfly --save

  2. 安装必要的渲染插件（如果不装，网页会显示乱码或报错）：

    Bash

    1
    npm install hexo-renderer-pug hexo-renderer-stylus --save

⚠️ 犯错预警（网络连接）： 你之前遇到了 port 443 连接超时的问题。如果 npm install 报错，请务必开启你的代理工具，或切换为国内镜像源： npm config set registry https://registry.npmmirror.com

第二步：应用主题

  1. 打开博客根目录下的 主配置文件 _config.yml。

  2. 找到 theme 字段，修改为：

    YAML

    1
    theme: butterfly

第三步：创建并编辑主题配置文件

为了方便以后升级主题而不丢失配置，建议不要直接去 node_modules 里改文件。

  1. 在博客根目录下新建一个文件，命名为：_config.butterfly.yml。

  2. 你可以从 Butterfly 官网配置文档 复制默认配置进去，或者先保持空白，逐步添加你需要的个性化设置（如头像、菜单等）。

第四步：本地预览与清理

每当更换主题或重大配置，必须执行“清理三部曲”：

Bash

1
2
3
hexo clean
hexo g
hexo s
  • 访问 http://localhost:4000 看看你的新主页是否变成了 Butterfly 风格。