鹏叔(https://pengtech.net)

导航

使用Hexo搭建自己的博客网站

1. 背景介绍

  • 本文是写给完全没有接触过技术的普通博客用户使用的，所以解释地比较细致，如果有技术基础，可以忽略其中的解释部分，按命令执行即可．

  • 说明：我的工作环境是deepin　linux, 处于安全性考虑一直运行在普通用户下, 如果你的安装环境是Mac 或者windows，请理解每一步骤的含义后执行调整命令或参数.
    或者在我的博客下面留言，我有空的时候会统一回复．

  • 说说我为什么选择Hexo, 目前比较主流的博客生成系统有三个hexo, jekyll和hugo，jekyll 是老牌的博客生成系统，搜到了github官方的支持，　但是是用的ruby的技术栈，
    我是技术出生ruby一直不在我的技术栈范围之内，至于jekyll和github在部署的时候的结合度更高的问题，我想对于一个做技术的人来说应该不是什么难事，应该比较容易处理．
    相比之下hexo使用的nodejs技术栈，hugo 是golang技术栈这两块技术栈我都比较熟悉，主要在这两个博客生成器系统之间徘徊． hugo固然速度更快，github上获得的星星数量也更多一些．由于考虑到博客系统更偏向于前端技术，这一块是nodejs特长，很多库都可以重用，从自己的职业嗅觉，我觉得一个博客系统或博客生成器采用nodejs技术栈更合适一点，另外很重要的一点Hexo Theme显得更成熟一些，所以我选择Hexo, hexo和hugo现在也很难说谁会在这一领域最终胜出．调查了一下，即使将来hugo胜出，迁移到hugo成本也不会太高．就我目前的个人需求和兴趣点来说，我还是比较偏向Hexo.

2. 安装Hexo

  • 安装Hexo之前需要安装nodejs, 可以参考我的博文安装并配置nodejs

  • 安装Hexo命令行工具

       # npm是nodejs 的包管理工具，sudo是linux或unix下将命令以管理员身份运行，install 为npm子命令用于安装工具包或项目依赖
   # -g为全局安装，安装一次后，在命令行中处于任何目录位置都能使用，如果不带-g 工具包被安装在当前项目的node_modules，
   # 需要借助npx才能执行相关命令，想hexo-cli这样的命令行工具建议全局安装
   # 这一步需要管理员权限，sudo即为以超级用户运行安装命令，linux 和mac 安装方法相同
   # 如果是windows环境可能需要以管理员身份运行，命令行前不需要sudo
   sudo npm install hexo-cli -g
  　或者
   # （推荐）如果访问墙外资源较慢，可以是cnpm经过阿里的镜像安装hexo-cli命令行工具，cnpm前面的c即为china的意思，wall内专用nodejs包管理工具
   sudo cnpm install hexo-cli -g

3. 创建博客系统

  • 初始化博客系统

    hexo init blog

    进入blog目录，安装项目依赖包(第三方nodejs类库或工具)

    cd blog
npm install

    命令说明：

    • hexo: 是hexo的命令

    • init: hexo的子命令，用于初始化一个博客系统．

    • blog: 是博客系统的名字，这里我没有考虑太多，直接将博客系统的名字命名为blog,　你可以根据自己的喜好设定名字．

    • 初始化完成后的简要目录结构如下:

      ./blog
    ├── _config.landscape.yml
    ├── _config.yml
    ├── db.json
    ├── node_modules
    ├── package.json
    ├── package-lock.json
    ├── scaffolds
    ├── source
    └── themes

      -目录结构说明

      • package.json: 这个是nodejs要用到的，里面存放着项目信息，版本，项目所依赖的第三方nodejs工具和代码库
      • package-lock.json: 这个nodejs解析依赖包时会用到的
      • scaffolds: 博客脚手架，当你创建新的博文时可以基于其中的某个模板进行修改．
      • source: 源代码文件夹，这里存放你网站的内容．
      • themes: 主题，博客css样式，背景图片等等．
      • node_modules: 这里存放npm install时从网络下载下来的依赖包
      • config.yml 项目配置文件

    • 配置文件详细说明

      • 这里重点说明一下项目配置文件．

      • 你可以修改项目的默认配置文件_config.yml以满足你个人的需求．比如标题，网站的描述，搜索关键字等等一些信息

        setting chines desc
        title 标题 你网站的标题
        subtitle 子标题 你网站的子标题
        description 网站描述 你网站的描述信息
        keywords 关键字 关键字
        author 作者 网站的作者
        language 语言 网站支持的语言

4. 本地启动博客系统

当前目录下执行以下命令，启动博客系统
$your_project_dir/blog/: $your_project_dir代表，你的博客系统所在目录

　hexo server

如果启动成功，会输出以下信息，最后一行会提示，通过什么网址可以访问博客．
打开浏览器，将网址粘贴到浏览器即可访问到博客系统．

$hexo server
INFO  Validating config
INFO  Start processing
INFO  Hexo is running at http://localhost:4000 . Press Ctrl+C to stop.

打开博客首页会看到一些默认的博客页面，后面我们将会讲解如何修改代码来构建自己的博客系统．

5. 创建第一篇博文

将一篇markdown格式的文章拷贝到source目录下，在博文开头加上标题，日期，标签页．
刷新浏览器，即可看到自己的第一篇博客文章．

6. 将博客发布到github

  • 创建一个以你的github用户名命名的代码仓库例如 guoapeng.github.io

  • 修改配置文件_config.yml配置代码库

      # Deployment
  ## Docs: https://hexo.io/docs/one-command-deployment
  deploy:
  type: git
  repo: git@github.com:your_github_id/your_github_id.github.io.git
  # example, https://github.com/hexojs/hexojs.github.io
  branch: gh-pages
    • 说明: 这里的url可以是http https 也可以是git url但是建议使用git url
    • 实测在push文件到github时使用https 路径，经常会有异常抛出，使用git　url后比较稳定
    • 使用https url 需要在url上添加授权方式和token 像这样repository: https://oauth2:yourtoken@github.com/*****.github.io, 实测可行 on Nov 1 2021

  • 修改package.json添加一条生产可发布博文的命令, 默认初始化项目时已经添加了该命令，如果没有则手动添加一下

      "scripts": {
  "build": "hexo generate",
}

  • 为了防止将一些非必要的文件推送到github仓库，创建一个.gitignore文件, 内容如下：

      .DS_Store
  Thumbs.db
  db.json
  *.log
  node_modules/
  public/
  .deploy*/

  • 创建gitHub token
    打开自己的GitHub主页，点击自己的头像找到Settings并进入, 选择developer settings 在左边目录栏找到Personal access tokens，点击Generate new token，按照步骤申请即可，过程简单。Scopes（范围）只需要授权 repo:status 和 repo:public_repo权限即可 。Token申请成功后，将Token复制并保存起来．当运行发布命令时需要输入此token作为密码

  • 安装hexo-git plugin

      npm install hexo-deployer-git --save
  或者
  cnpm install hexo-deployer-git --save　//推荐

  • 这样前期准备工作基本完成，现在开始发布博客
    发布博客系统使用如下命令:

      hexo clean && hexo generate && hexo deploy

    当提示输入git用户名密码时，输入你的github用户名, 当提升输入密码时，输入上面生成的token

  • 浏览器打开自己的博客首页 https://guoapeng.github.io/

  • 由于我设置了dns cname所以实际会跳转到https://www.pengtech.net/

  • 回头看一下hexo上传了哪些文件到github, 其实只是上传了编译后的文件

  • 所以需要自己将源文件保存到一个私有仓库，或者上传到另一个github仓库

      2021/10/04/post
  archives
  css
  fancybox
  js
  tags/Hexo
  index.html

7. 进阶: 如何开启评论, 转发, 优化界面等等

可以参考我的文章 Hexo博客添加评论功能

更多Hexo相关主题可以访问我的博客hexo主题https://www.pengtech.net/hexo/

8. 参考文档

Hexo官方文档

Hexo 配置文档

9. trouble shooting

    1. 启动时遇到err: Error: ENOSPC: System limit for number of file watchers reached

    • 具体错误信息如下

          $hexo server
    INFO  Validating config
    INFO  Start processing
    FATAL {
    err: Error: ENOSPC: System limit for number of file watchers reached, watch '$your_project_dir/blog/source/'
    at FSWatcher.<computed> (internal/fs/watchers.js:218:26)
    at Object.watch (fs.js:1582:34)
    at createFsWatchInstance ($your_project_dir/blog/node_modules/chokidar/lib/nodefs-handler.js:119:15)
    at setFsWatchListener ($your_project_dir/blog/node_modules/chokidar/lib/nodefs-handler.js:166:15)
    at NodeFsHandler._watchWithNodeFs ($your_project_dir/blog/node_modules/chokidar/lib/nodefs-handler.js:331:14)
    at NodeFsHandler._handleDir ($your_project_dir/blog/node_modules/chokidar/lib/nodefs-handler.js:559:19)
    at processTicksAndRejections (internal/process/task_queues.js:95:5)
    at async NodeFsHandler._addToNodeFs ($your_project_dir/blog/node_modules/chokidar/lib/nodefs-handler.js:609:16)
    at async $your_project_dir/blog/node_modules/chokidar/index.js:451:21
    at async Promise.all (index 0) {
    errno: -28,
    syscall: 'watch',
    code: 'ENOSPC',
    path: '$your_project_dir/blog/source/',
    filename: '$your_project_dir/blog/source/'
    }
    } Something's wrong. Maybe you can find the solution here: %s https://hexo.io/docs/troubleshooting.html

    • 解决办法
      扩大能watch的文件数上限

        echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

  • 2 The TLS connection was non-properly

      fatal: unable to access 'https://github.com/xxxx/xxxx.github.io/': gnutls_handshake() failed: The TLS connection was non-properly terminated.
  FATAL {
  err: Error: Spawn failed
  at ChildProcess.<anonymous> ($your_project_dir/blog/node_modules/_hexo-util@2.5.0@hexo-util/lib/spawn.js:51:21)
  at ChildProcess.emit (events.js:400:28)
  at Process.ChildProcess._handle.onexit (internal/child_process.js:277:12) {
  code: 128
  }
  } Something's wrong. Maybe you can find the solution here: %s https://hexo.io/docs/troubleshooting.html

    • 原因
      　其实出现这个问题，很大可能是因为https和http的proxy的对应的分别是https和http开头的proxy server，而https的proxy server可能无法正常工作。一个work around是把https的proxy server换成http的proxy server:

    • 解决办法
      解决办法有三种,
      修改_config.yml文件的deploy部分，将https 修改为http url 或者 设置为git url, 配置为https oauth2 加token

      1. git url
      deploy:
  type: git
  repo: git@github.com:your_github_id/your_github_id.github.io.git
  branch: gh-pages

      这里建议配置为git　url
      2. http url

      deploy:
  type: git
  repo: git@github.com:your_github_id/your_github_id.github.io.git
  branch: gh-pages
      1. 在repo https url上要添加授权方式和token
        deploy:
    type: git
    repo: https://oauth2:your_github_token@github.com/your_github_id/your_github_id.github.io.git
    branch: gh-pages

  • 3 站内链接跳转问题

    • 当时使用markdown标准的站内跳转链接写法时，再发布后发现链接是错的跳转不过去，例如

         [如何创建一个nodejs模块](how_to_create_a_node_module.md)
      • 发现生成的链接是不对的，路径上缺少了年月等信息

    • 解决办法

      • 替换为下面这种写法，就能正确跳转

          {% post_link nodejs/how_to_create_a_node_module %}

      • 更多详细分析可以参考知乎上的这篇文章

  • 4 链接包含中文不能正常跳转问题

    • 现象：当右侧大纲条目中包括中文时，点击不能正确跳转

      • 打开浏览器开发者模式发现以下错误

        utils.js:240 Uncaught TypeError: Cannot read property 'getBoundingClientRect' of null
at HTMLAnchorElement.<anonymous> (utils.js:240)

    • 原因分析:
      中文链接在转码后不能正确的映射到相应的页面元素

    • 解决方案

      • 我已经通过此issue反馈给hexo社区，社区的回复是在新的Next theme中已经解决此问题，需要升级 next theme到新版本, 以下是来自社区的回复:

        This issue has been fixed in next-theme/hexo-theme-next@0d2b3af
Theme NexT version 7.8.0 is outdated. The latest version is v8.8.0 https://github.com/next-theme/hexo-theme-next/releases/tag/v8.8.0

posted on 2021-10-08 16:54  eagle.supper  阅读(184)  评论(0)  编辑  收藏  举报