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

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

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

• 说明：我的工作环境是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,

安装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
  

创建博客系统

• 初始化博客系统

  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	语言	网站支持的语言

本地启动博客系统

当前目录下执行以下命令，启动博客系统
$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.

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

创建第一篇博文

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

将博客发布到github

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

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

    # Deployment
    ## Docs: https://hexo.io/docs/one-command-deployment
    deploy:
    type: git
    repo: git@github.com:guoapeng/guoapeng.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后比较稳定

• 修改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（范围）那里建议全选。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/

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

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

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

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

可以参考我的文章 Hexo配置Next主题

参考文档

Hexo官方文档

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 或者 设置为git url
    这里建议配置为git　url

• 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