hexo+github搭建个人博客教程和各种坑

记录使用github pages服务搭建个人博客的详细过程以及遇到的各种坑

hexo+github搭建个人博客教程

1.前言

1.1 准备工作

环境 ： win10

• 注册github账号：https://github.com/

• 下载安装node.js:官网下载https://nodejs.org/en/

  下载后图形化界面安装，安装成功后运行cmd 输入node -v，显示版本信息即为成功

  下载npm：由于新版的nodejs已经集成了npm，所以之前npm也一并安装好了。同样可以通过输入 “npm -v” 来测试是否成功安装

• 下载git,配置好用户名密码邮箱

  2.搭建博客

  2.1github创建仓库

  在github网页新建一个仓库并命名为你的用户名.github.io的仓库，注意：

  • 验证注册的邮箱

  • 仓库名必须为用户名.github.io

  • 仓库创建后需要等待一会

    2.2 配置ssh-key

    首先打开git bush ,执行

    $ cd ~/. ssh #检查本机已存在的ssh密钥
    

    如果提示：No such file or directory 说明你是第一次使用git ：

    ssh-keygen -t rsa -C "邮件地址"
    

    然后连续3次回车，最终会生成一个文件在用户目录下，打开用户目录，找到.ssh\id_rsa.pub文件，记事本打开并复制里面的内容，打开你的github主页，进入setting -> SSH and GPG keys -> New SSH key：

  打开命令行或者git bash，输入

  $ ssh -T [email protected] # 注意邮箱地址不用改
  

  如果提示Are you sure you want to continue connecting (yes/no)?，输入yes，然后会看到： Hi xxx …!

如图，即为配置成功，然后输入

$ git config --global user.name "liuxianan"// 你的github用户名，非昵称
$ git config --global user.email  "[email protected]"// 填写你的github注册邮箱

3.配置hexo

3.1 hexo

Hexo是一个简单、快速、强大的基于 Github Pages 的博客发布工具，支持Markdown格式，有众多优秀插件和主题。

官网： http://hexo.io
github: https://github.com/hexojs/hexo

• 推荐完全在git bash 执行命令

• hexo不同版本差别较大，注意区分

• hexo有两种_config.yml文件 ，一个是根目录下的全局的_config.yml，一个是各个theme下的

  3.2hexo安装

  $ npm install -g hexo
  

  新建hexo文件夹，这个文件夹将作为你存放代码的地方

  切到hexo文件夹打开命令行，运行

  $ hexo init
  

hexo会自动下载一些文件到这个目录，包括node_modules：

$ hexo g # 生成
$ hexo s # 启动服务

执行以上命令之后，hexo就会在public文件夹生成相关html文件，这些文件将来都是要提交到github去

hexo s是开启本地预览服务，打开浏览器访问 http://localhost:4000 即可看到内容

如果端口占用，运行以下：

1. 按下Win+R调出命令行窗口，输入netstat -aon|findstr "4000"，找到指定行最后一列的数字（PID）
2. 输入tasklist|findstr "PID"，发现是xxx用了4000端口。
3. 再次输入taskkill /f /t /im xxx.exe结束该进程。

第一次初始化的时候hexo已经帮我们写了一篇名为 Hello World 的文章，默认的主题比较丑

3.3修改主题

以主题 https://github.com/esappear/hexo-theme-clover 为例：

可在 https://hexo.io/themes/ 查找更多主题

推荐主题 http://theme-next.iissnan.com/getting-started.html

在博客根目录:

$ git clone https://github.com/blleng/hexo-theme-lx themes/lx

更改站点设置文件_config.yml:

theme: lx

然后重新执行hexo g来重新生成。 如果出现一些莫名其妙的问题例如样式崩了，可以先执行hexo clean来清理一下public的内容，然后再来重新生成和发布

3.4 上传到github

在上传代码到github之前，一定要记得先把你以前所有代码下载下来（虽然github有版本管理，但备份一下总是好的），因为从hexo提交代码时会把你以前的所有代码都删掉。

配置好ssh-key后，配置hexo文件夹中的_config.yml:

deploy :
  type: git
  repository: [email protected]:lishoushoua/lishoushoua.git
  branch: master

• 注意！deploy后要有一个空格，否则hexo d会报错

  此时直接执行hexo d的话一般会报如下错误：

Deployer not found: github 或者 Deployer not found: git

安装一个插件：

npm install hexo-deployer-git --save

• 注意！要在git bash 中运行命令， 否则会提示Permission denied (publickey)

打开你的git bash，输入hexo d就会将本次有改动的代码全部提交，没有改动的不会：

刷新github page页面,即可显示

3.5常用hexo命令

hexo new "postName" #新建文章
hexo new page "pageName" #新建页面
hexo generate #生成静态页面至public目录
hexo server #开启预览访问端口（默认端口4000，'ctrl + c'关闭server）
hexo deploy #部署到GitHub
hexo help  # 查看帮助
hexo version  #查看Hexo的版本

hexo n == hexo new
hexo g == hexo generate
hexo s == hexo server
hexo d == hexo deploy

hexo s -g #生成并本地预览
hexo d -g #生成并上传

3.6_config.yml

在Hexo中有两个很重要的名为_config.yml的文件，其中一个在站点安装的根目录下，另一个在主题目录下。前者提供了Hexo自身的一些基本配置信息，后者为你所安装的主题的相关配置。为了方便区分，我们把前者称为站点配置文件，后者称为主题配置文件。

站点配置文件

文件路径站点根目录/_config.yml
这里贴一下个人的部分配置，可以改一下相关内容自行体会一下效果：

# Site
title: cuteerha
subtitle: Live well,love lots,and laugh often
description: 个人学习记录
keywords:
author: cuteerha
language: en
timezone: Changchun

“title”：博客的名称。
“subtitle”：根据主题的不同，有的会显示有的不会显示。
“description”：主要用于SEO，告诉搜索引擎一个关于站点的简单描述，通常建议在其中包含网站的关键词。
“author”：作者名称，用于主题显示文章的作者。
“language”：语言会对应的解析正在应用的主题中的languages文件夹下的不同语言文件。所以这里的名称要和languages文件夹下的语言文件名称一致。
“timezone”：可不填写。

# URL
## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'

url: https://lishoushoua.github.io/lishoushoua.github.io/
root: /lishoushoua.github.io/
permalink: :title/
permalink_defaults:
pretty_urls:
  trailing_index: true # Set to false to remove trailing index.html from permalinks

“url”：一般填写自己的站点链接。
“root”：设置根目录的位置。如果你的网站存放在子目录中，例如 http://yoursite.com/blog，则应该将你的 url 设为http://yoursite.com/blog 并把 root 设为 /blog/。
“permalink”：生成的链接的格式。带井号的是默认的格式，带有日期感觉怪怪的，改成了自己喜欢的格式。规则也比较简单，标签前面要加英文冒号。
“permalink_defaults”: 生成链接中各部分的默认值

# Directory
source_dir: source
public_dir: public
tag_dir: tags
archive_dir: archives
category_dir: categories
code_dir: downloads/code
i18n_dir: :lang
skip_render:

# Writing
new_post_name: :title.md # File name of new posts
default_layout: post
titlecase: false # Transform title into titlecase
external_link: true # Open external links in new tab
filename_case: 0
render_drafts: false
post_asset_folder: false
relative_link: false
future: true
highlight:
  enable: true
  line_number: true
  auto_detect: false
  tab_replace:

书写相关的设置
“new_post_name”：新的博文的文件名
“default_layout:“ 默认布局
“filename_case: 0“ #把文件名称转换为 (1) 小写或 (2) 大写
“render_drafts: false“ 是否显示草稿
“post_asset_folder: false“ #是否启动资源文件夹
“relative_link: false“ #把链接改为与根目录的相对位址
“future: true “
“highlight:“ #代码块的设置，Hexo自带的代码高亮插件

# Category & Tag
default_category: uncategorized
category_map:
tag_map:

分类和标签的设置
“default_category”：如果撰写文章时没有设置分类，默认的分类选择。
“category_map”：用于映射分类的别名。
“tag_map”：用法和分类别名是一样的。

# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: next

# Deployment
## Docs: https://hexo.io/docs/deployment.html
deploy :
  type: git
  repository: [email protected]:lishoushoua/lishoushoua.git
  branch: master

“theme”：主题拓展，可以在主题商店选择其他主题，这里使用next
“deploy”：部署方式

4.遇到的问题

4.1关于hexo安装失败的解决方法

可能国内npm源有问题，键入一下代码即可成功安装

npm install -g cnpm --registry=https://registry.npm.taobao.org
cnpm install hexo-cli -g

4.2出现****‘git’**** 不是内部或外部命令，也不是可运行的程序

Windows下配置Git,配置环境变量path

• 找到git安装路径中bin的位置，如：D:\Program Files\Git\bin
• 找到git安装路径中git-core的位置，如：D:\Program Files\Git\libexec\git-core;
• 右键“计算机”->“属性”->“高级系统设置”->“环境变量”->在下方的“系统变量”中找到“path”->选中“path”并选择“编辑”->将找到的bin和git-core路径复制到其中->保存并退出
• 注：“path”中，每个路径之间要以英文输入状态下的分号——“;”作为间隔

4.3 npm ERR! Error: EPERM: operation not permitted

权限问题，使用管理员权限打开命令行，也可以对hexo所在文件夹修改相应的用户权限

4.4 git push没有权限

Permission denied (publickey).fatal: Could not read from remote repository.

1. 先看本地是否有ssh文件

   > cd ~/.ssh
   

2. 有则把公钥加到github,参见前文配置密钥

3. 执行 ssh -T [email protected] 出现如下提示，本地公钥没有问题

   > ssh -T [email protected]
   Hi lishoushoua! You've successfully authenticated, but GitHub does not provide shell access.
   

4.5nothing to commit, working tree clean

hexo进行提交博客，使用hexo d命令，但需要是使用 hexo-deployer-git 包的，如果没有安装，它检索不到博文，进而提交时，让github发现项目没有发生变化，于是提交失败，弹出这种提示。

安装 hexo-deployer-git

 npm install hexo-deployer-git 

4.6 github page没有样式

url地址没有配置正确，修改_config.yml文件的url地址和根目录

url: https://lishoushoua.github.io/lishoushoua.github.io/
root: /lishoushoua.github.io/

有可能是hexo缓存的问题，也就是网站根目录的db.json出了问题，建议清除下缓存 清除缓存的方法： 执行命令：hexo clean 然后生成静态博客，在本地预览:

$hexo clean
$hexo g
$hexo d

4.7 github更换next主题后404

排除主题和 CNAME 问题，出现 404 ，首先判断是缺少 index.html ，所以肯定就是静态页面文件不全，可以查看.deploy_git 目录下是否有 index.html，运行以下命令解决：

 npm install hexo-generator-index --save