缘起及过程

一直觉得有个人主页是一件挺酷的事，特别是对于我们这些计算机专业出身的人来说。大一下学期准备从信息科学技术学院转到人工智能与数据科学学院（当时还叫大数据学院），新学院的学生会做了个进阶指南网站（类似于上海交通大学生存手册），在里面看到一篇搭建个人学术主页的教程，遂按照上面的指导，尝试使用academicpages搭建个人网站。先是按文中提到的知乎答主超级懒的小周撰写的中文教程（教程现已不存，但相关Github仓库还在）进行搭建，fork了他的仓库，初步了解了Github Pages和静态网站和动态网站的区别，并下载了Node.js和Hexo，不过由于当时没写什么东西，而且对git相关操作、网站搭建等非常陌生，就决定暂时搁置。暑假时想拥有一个自己的域名，也为了方便在国内访问，于是在阿里云购买了一个域名（期限一年），并租了一年的服务器，加起来花了一百多块钱（阿里云有针对大学生的三百元优惠，但并不适用于购买域名）。买了域名还需要向工信部备案，流程略有些繁琐，但最后都办下来了。大二一年学业繁忙，没心思弄个人主页，域名和服务器到期后也不想续费了，结果那段时间天天被阿里云短信轰炸，不胜其烦。到了大三上学期，又开始想做一个学术主页，在网上发现了academicpages的教程和仓库，遂又开始fork、git clone一顿操作，搭建出一个学术主页的基本框架，但还没放什么东西上去。原本想着有一个学术主页就够了，但是在2024年11月14日晚上刷阮一峰的科技爱好者周刊时，被别人简洁优美的博客网站所吸引，加上今年以来写了不少游记，于是心血来潮，想再做一个只记录日常生活随想的个人博客，上次做的学术主页将主要用于更正式的场合。

笔者搭建这个网站时，主要的参考资料是：《快速搭建个人博客——保姆级教程》、Butterfly主题的官方文档、《Hexo 博客上手入门指南、性能优化、界面美化、扩展功能、各种疑难杂症等解决方案全系列合辑》，三者已经能解决用Hexo框架+Butterfly主题搭建个人博客的绝大部分问题。一开始为了方便国内访问，准备用Gitee的个人主页功能，但笔者把框架建好后发现gitee.io一直登不上，一查才知Gitee已经不再支持免费的静态网站服务了，至于其他的免费网站服务，比较知名的是cloudflare，B站上有相关教程，但笔者不太熟悉，而且这也是国外的服务，对于国内的用户，访问速度可能和Github没有太大的区别，所以笔者重新注册了一个Github账号，计划新的个人博客一开始仍使用Github Pages，然后就是一系列git clone、npm install xxx、hexo clean、hexo g、hexo s、hexo deploy操作，在框架没问题后就进行一些细节的调整和美化，并将博文以markdown格式上传到根目录的source/_posts文件夹下，因为笔者对markdown相关语法和操作比较熟悉，因此在最后这步没有碰到太大问题。由于Hexo框架+Butterfly主题的功能和教程已经比较完善（例如目录、相关推荐、底部的版权信息、转发等功能都已自动实现），基本能满足笔者的需求，所以后期的修改并没有花太多时间。笔者是从周四晚上开始搭建这个网站的，到下周一晚上就基本完成了（其间还赶了不少DDL），后面主要是专注于内容的发布与各种微调。到了12月底，觉得用Github Pages在国内访问不方便，于是又在阿里云上购买了域名kangaroogao.com（3年252元），并租了最低配置的云服务器（1年99元），按教程将博客部署到阿里云服务器上，并在工信部和公安部备案。2025年1月初，笔者误将博客所在的文件夹删除（至今不知原因），只能从服务器上下载public文件夹，将其中的index.html文件还原为.md文件，使用beautifulsoup4库只能做到大体还原，后来也尝试了pandoc工具，同样需要手动修改很多细节，总之又折腾了两天（在网上也没找到更好的方法）。

一些bugs和解决方案

  1. 第一次hexo s后在本地服务器能正常显示，但是hexo deploy后无法在网站上显示主题和图片，经过搜索，得知需要在_config.yml的url下添加root，比如：

    1
    2
    url: https://kangaroogao.com/
    root: /

    注意在.yaml中，冒号后面要有一个空格。

  2. Github的用户名需要和仓库名一致，并且全部为小写字母或数字，笔者一开始使用了大写字母，发现Github会将其自动改为小写，导致无法访问。

  3. 设置顶部图default_top_img时，笔者一开始用的是本地的文件路径（无论是相对路径还是绝对路径，也试过放在img文件夹下），都在网站上无法显示，后来将图片上传到了一个免费的图床网站（也可以直接上传到Github仓库，但会影响国内的加载速度），然后将图片的url放到default_top_img后，这样就能正常显示了。想在文章中嵌入图片也同样需要使用图片链接而非本地路径。

  4. 笔者新设了一个Github账号用来搭建本博客，但并不需要切换git全局配置，只需要在_config.yml中修改配置如下：

    1
    2
    3
    4
    deploy: 
        type: git
        repository: git@github.com:kangaroogao/kangaroogao.com.git
        branch: main

    但修改后还是报错，查资料得知hexo deploy使用SSH连接到Github，因此还需在C:\Users\admin\.ssh\config (Windows) 或~/.ssh/config (Linux) 中添加如下内容：

    1
    2
    3
    4
    5
    Host github.com
        Hostname ssh.github.com
        Port 443
        User git
        IdentityFile

    其中IdentityFile 后需要写入自己的私钥路径，生成私钥的方式可参考网络资料，而Hostname和Port是为了解决如下报错：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    ssh: connect to host github.com port 22: Connection timed out
    fatal: Could not read from remote repository.

    Please make sure you have the correct access rights
    and the repository exists.
    FATAL Something's wrong. Maybe you can find the solution here: https://hexo.io/docs/troubleshooting.html
    Error: Spawn failed
        at ChildProcess.<anonymous> (D:\Blog\node_modules\hexo-util\lib\spawn.js:51:21)
        at ChildProcess.emit (node:events:514:28)
        at cp.emit (D:\Blog\node_modules\cross-spawn\lib\enoent.js:34:29)
        at ChildProcess._handle.onexit (node:internal/child_process:291:12)

  5. 笔者一开始想使用hexo-douban插件爬取豆瓣电影个人主页，但发现这个\movies页面无法显示自定义的标题，而是显示网站的标题”Maohang Gao’s Blog”（之前尝试时还能正常显示），可能是由于butterfly主题更新，导致渲染逻辑改变了。通过向插件作者提issue，作者建议使用idouban，于是笔者新建了一个movies页面，并在movies/index.md写入如下内容：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    ---
    title: Movies
    ---
    <body>
    <div id="douban"></div>
    </body>
    <link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/idouban/dist/index.css"/>
    <script
    src="https://cdn.jsdelivr.net/npm/idouban/dist/index.js"
    onload="idouban.init({
            selector: '#douban',
            lang: 'zh',
            douban_id: '258576743',
            type: 'movie',
            quote: '豆瓣电影个人主页',
            actions: ['collect', 'wish'],
            page_size: 10,
            max_line: 4
            })"
    ></script>

    如果采取idouban的方式，应该将原来hexo-douban的配置删除。另外，假如使用了hexo-douban插件，就不能使用hexo d作为hexo deploy的缩写了。

  6. 使用hexo-tag-aplayer插件插入本地音乐时，需要在source目录下新建一个music文件夹，然后将音乐文件（能播放的主要是.mp3）放入其中，在文章 .md 文件中想插入音乐的位置写如下格式的代码：

    1
    2
    3
    <script src="https://cdn.jsdelivr.net/npm/aplayer/dist/APlayer.min.js"></script>

    {% aplayer title author url [picture_url, narrow, autoplay, width:xxx, lrc:xxx] %}

    例如：

    1
    2
    3
    <script src="https://cdn.jsdelivr.net/npm/aplayer/dist/APlayer.min.js"></script>

    {% aplayer "鸭子" "苏慧伦" "/music/鸭子.mp3" %}

    注意：再在文章中插入音乐时，路径应为/music/音乐文件名（音乐文件名可以为中文），笔者一开始写成music/音乐文件名就无法正常播放。此外，<script src="https://cdn.jsdelivr.net/npm/aplayer/dist/APlayer.min.js"></script>也是必不可少的，不然会报错Uncaught ReferenceError: APlayer is not defined。此外，在本地服务器上运行时可能无法拖动音乐进度条。关于hexo-tag-aplayer插件的更多用法（如插入外部音源），可以参考插件官方文档以及Butterfly主题文档的相关内容，遇到其他一些bug时，可以通过浏览器开发者工具查看具体的错误信息并进行调试。

  7. 在Github Pages的Custom domain里写入自己的域名，但每次执行hexo deploy后访问自己的域名都会报404错误，发现Custom domain已经被重置为空，为了避免每次都要手动修改，需在根目录下的source文件夹里新建CNAME文件，里面写入自己的域名如kangaroogao.com即可。

一些small tips

  1. hexo deploy后网页没有变化，可以刷新几次，如果还是没有变化，可以尝试清除浏览器缓存。如果想马上看到修改效果，可以在hexo g后执行hexo s，这样网站会在本地服务器上显示。

  2. 想要给文章设置封面，首先需在themes/butterfly_config.yml的cover下的default_cover设置默认封面地址，然后在文章的front-matter中写入cover字段，如：

    1
    2
    3
    4
    5
    6
    7
    ---
    title: 今古一相接，长歌怀旧游——国庆出游杂记
    tags: 行走足迹
    categories: 游记
    date: 2024-10-7
    cover: https://s3.bmp.ovh/imgs/2024/12/31/242b2ce1ecaf1bf3.jpg
    ---

    对butterfly主题中设置文章封面后，在首页文章列表中会显示完整封面图，但在文章页面里只会显示封面图的一部分，显得很不美观，因此暂时放弃了这个功能，转为在文章里插入图片。

  3. 为了添加RSS订阅功能，需要执行npm install hexo-generator-feed --save下载插件，但默认的RSS页面如下，显得很不美观：

    后来在阮一峰的科技爱好者周刊看到了一个 RSS 美化工具，可以访问官网，把atom.xsl下载到source文件夹里，并在根目录下的_config.yml里添加

    1
    2
    3
    4
    5
    6
    7
    8
    9
    feed:
        type: atom
        path: atom.xml
        limit: 20
        hub:
        content: 
        content_limit: 140
        content_limit_delim: ' '
        order_by: -date

    然后在node_modules\hexo-generator-feed\atom.xml文件第一行的<?xml version="1.0" encoding="utf-8"?>后面添加<?xml-stylesheet type="text/xsl" href="/atom.xsl"?>即可。美化后的效果（不能通过本地服务器查看）如下：

  4. 将博客部署到阿里云服务器前，需要将DNS解析的信息改为类似如下的内容（注意下面这个表格要用html而非markdown写，否则会因为有缩进而无法正确渲染）：

    记录类型 主机记录 记录值 TTL
    A @ 121.41.118.33 600
    A www 121.41.118.33 600

    其中记录类型应改为A，而不是原来的CNAME，记录栏是服务器的ip地址，而不是原来的.github.io，部署后发现访问https://kangaroogao.com/会报404错误，只能访问http://kangaroogao.com，为了能用https访问，需要在阿里云上购买并申请CA证书（笔者的一年44.8元）。

  5. 为了让网站内容支持浏览器搜索，需要安装hexo-generator-sitemap插件（不需要hexo-generator-robotstxt），然后在_config.yml中添加如下内容：

    1
    2
    sitemap:
        path: sitemap.xml

    在 Hexo 项目的source目录中创建一个robots.txt文件，内容如下:

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

    否则会报错：

    1
    2
    3
    4
    5
    6
    7
    8
    TypeError: Cannot read properties of undefined (reading 'useragent')
    at data (D:\Blog\node_modules\hexo-generator-robotstxt\index.js:6:37)
    at tryCatcher (D:\Blog\node_modules\bluebird\js\release\util.js:16:23)
    at D:\Blog\node_modules\bluebird\js\release\method.js:15:34
    at RouteStream._read (D:\Blog\node_modules\hexo\lib\hexo\router.js:47:5)
    at Readable.read (node:internal/streams/readable:496:12)
    at resume_ (node:internal/streams/readable:999:12)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21)

    此外可以在百度搜索资源平台、Bing网站管理员工具添加自己的网址。在百度搜索资源平台遇到“您无权访问该页面，点击确定按钮返回首页”或“验证码错误”的问题时，关掉vpn重试几次或换别的浏览器即可。

  6. Hexo默认按照年、月、日、标题来生成文章链接。如果标题有中文，生成的链接可能无法访问，或者长度过长影响推广，如https://kangaroogao.com/2024/09/19/%E2%80%9C%E4%BA%BA%E7%94%9F%E7%9F%AD%E7%9F%AD%E5%87%A0%E4%B8%AA%E7%A7%8B%EF%BC%8C%E4%B8%8D%E9%86%89%E4%B8%8D%E7%BD%A2%E4%BC%91%E2%80%9D%E2%80%94%E2%80%94%E5%9C%A8%E6%B4%9B%E9%98%B3%E3%80%81%E9%83%91%E5%B7%9E%E7%9A%84%E4%B8%AD%E7%A7%8B/。我们可以使用npm install hexo-abbrlink -- save安装一个插件，该插件会为每篇生成一个唯一字符串标识，并且不受文章标题和发布时间的影响。修改博客根目录下的配置文件_config.yml中的permalink配置项为：

    1
    2
    3
    4
    5
    6
    permalink: posts/:abbrlink/

    # 增加abbrlink配置
    abbrlink:
        alg: crc16   #算法： support crc16(default) and crc32
        rep: hex     #进制： support dec(default) and hex

    以上述链接为例，使用插件重新生成后变为https://kangaroogao.com/posts/4186/，明显短了很多。

  7. 为了删除已发表的文章，需要在文件夹source/_posts中删除相应的.md文件，并删除.deploy_git文件夹（该文件夹由hexo deploy创建，hexo clean无法将其删除）。