Currently this site utilizes Pagefind to search with relatively high degree of accuracy in English. To search in Chinese, it is recommended to split the keywords into groups of words(up to two words) and include them in the symbol ". For example, if you want to search for 区块链 or 智能合约, you can use "区块 链" and "智能 合约" and you may get better results.

If you are not satisfied with the search results or would like to know more, please feel free to share with me by leaving a comment on any of the articles, or email me at wongbingming@163.com.

It makes use of a variety of open source projects including:

• Cobra
• Viper
• J Walter Weatherman
• Cast

Learn more and contribute on GitHub.

而最后一个 WordPress 比较重，需要消耗不少服务器资源，访问人数多了后，也比较卡，弃用的念头已经非常强烈，刚好前两天服务器到期，就打算重新换个轻量的静态框架。

经过一番调研，出于颜值和性能的要求，最终选择了 Hugo ！不可否认，选择 Hugo 也有一部分原因是我当前以 Go 开发为主，就跟当初写 Python 代码时，选择用 Sphinx 搭建同理。

以下操作仅以 macOS 为例，Windows 请自行尝试，除了工具安装方式有区别外，其他区别不大，可放心食用。

1. 安装 Hugo

首先在电脑上安装 hugo 二进制

brew install hugo

初始化站点

hugo new site iswbm.com

初始化 git 仓库

git init
git add -A
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:iswbm/iswbm.com.git

2. 引入主题

让我决定选择使用 hugo，其实就是无意中浏览了 pseudoyu 的个人站点（https://www.pseudoyu.com/），非常钟意这个主题。

pseudoyu 使用的是 hugo-theme-den 主题，并基于此主题做了一些个性的定制。

而 pseudoyu 关于此部分的定制貌似没有在 github 上更新，于是我只能自己研究将搜索植入主题中。

要使用我改过的主题，可以按照我的步骤来操作

# 添加子模块
git submodule add https://github.com/iswbm/hugo-theme-den.git themes/hugo-theme-den

后续如果我的主题有更新，你都可以直接使用如下命令来更新

git submodule update --remote

hugo-theme-den主题会提供了实例配置与初始页面，开始使用主题时可以将其 exampleSite/ 目录下的文件复制到站点目录下，在此基础上进行调整配置。

cp -rf themes/hugo-theme-den/exampleSite/* ./

初始化主题基础配置后，我们可以在 config.toml 文件中进行站点细节配置，具体配置项参考各主题说明文档。

将拷贝过来的文件，加入到自己的仓库中

git add -A
git commit -m "use hugo-theme-den"

3. 发布新文章

通过 hugo new 命令可以在 content/zh 目录下新建文章

hugo new posts/first-post.md

模板的内容，可以自行修改 archetypes/default.md ，我的模板是

---
title: '{{ replace .File.ContentBaseName "-" " " | title }}'
date: {{ .Date }}
draft: false
lastmod: {{ .Date }}
tags: ["python"]
categories: ["Programming"]
authors:
- "iswbm"
---

新建文章后，用 vscode 或 typora 等 markdown 编辑器可以写一些内容。

完成内容的补充后，可以用如下命令直接运行 http 的服务器（若你的模板里指定draft=true，这里就直接执行 hugo server 即可）

hugo server --buildDrafts --ignoreCache

然后访问 http://localhost:1313

‍

4. Pagefind 搜索

在个人博客支持文章搜索，是一个非常刚需的需求。

正常的网站都是在后端检索再返回给前端，但 hugo 生成的是静态的 HTML 文件，想要在这样的网站上支持搜索，就得提前将网站的文章进行分析，生成静态的索引文件。

用 Pagefind 可预生成索引文件，后续用户的搜索全部在客户端完成，可以快速加载并减少服务器负载，是一种非常轻量的解决个人博客搜索的方案。

Pagefind 是开源项目

• 仓库地址：https://github.com/CloudCannon/pagefind
• 二进制下载：https://github.com/CloudCannon/pagefind/releases

使用时只需要下载二进制文件即可，以本人是 macOS 的为例（根据自己电脑选择合适的二进制版本）

wget https://github.com/CloudCannon/pagefind/releases/download/v1.1.0/pagefind-v1.1.0-x86_64-apple-darwin.tar.gz
tar -xvf pagefind-v1.1.0-x86_64-apple-darwin.tar.gz
mv pagefind /Users/iswbm/.local/bin/

若不创建任何的配置文件，可以直接将关键配置以参数形式指定

pagefind --source public --bundle-dir pagefind

也可以将配置写入配置文件中，在项目根目录创建 pagefind.yml

# 生成的 pagefind 的目录
site: "public"
output-path: "pagefind"

# 指定要索引的源目录，通常是 Hugo 生成的静态文件目录
#contentDir: "public"

# 指定输出索引文件的目录
#indexDir: "static/pagefind"

# 指定静态文件的 URL 前缀，这通常与你的 Hugo 网站的 URL 结构相匹配
#baseURL: "https://example.com"

# 指定要索引的文件类型，例如 .html
indexDocs: [".html"]

# 指定要排除索引的文件或目录的 glob 模式
excludeFiles: ["**/404.html", "*/noindex/*"]

# 指定要包含的字段，这些字段将被索引用于搜索
fields: ["title", "description", "content"]

# 指定用于生成摘要的字段
excerptField: "excerpt"

# 指定用于搜索结果标题的字段
titleField: "title"

# 指定用于搜索结果 URL 的字段
#urlField: "link"

# 指定用于搜索结果内容的字段
#contentField: "content"

# 指定是否将 HTML 内容转换为纯文本
#htmlAsText: true

# 指定是否启用对中文语言的支持
chinese: true

# 指定是否在控制台中显示详细的日志信息
verbose: false

# 指定是否跟踪堆内存使用情况
traceHeap: false

# 指定是否启用调试模式
debug: false

以后只需要直接执行 pagefind ，就会在 public/zh 目录下生成 pagefind 目录（即索引文件）

有了索引后，还需要有一个搜索的页面。

在 content/zh 和 content/en 下各新增一个 search.md 文件，中文的版本如下

---
title: "搜索"
layout: search
menu: "main"
weight: 20
---

>目前本网站应用 [Pagefind](https://pagefind.app/) 进行搜索，英文准确度较高，若要检索中文，建议把关键词拆分成最多两个字一组，并包含在符号 `"` 之中。例如若要搜索 `区块链` 或 `智能合约`，可以使用 `"区块 链"` 和 `"智能 合约"`，可能会有更好的搜索结果。

>如果你对搜索结果不太满意或想了解更多，欢迎通过任意文章留言与我分享，或发送邮件至 `wongbingming@163.com`，告诉我你的想法。

由于指定了 menu:"main" ，因此会直接新增一个菜单，效果如下

搜索的效果如下

5. 部署上线

一切调度完成后，需要将网站部署到服务器上才可能公网访问。

如果自己没有服务器的，可以自行购买一个，618 将近，各大厂商也开始打折促销，可以点我下面的链接领个卷再去购买比较划算

• 阿里云：https://iswbm.com/alicloud
• 腾讯云：https://iswbm.com/txcloud
• Ucloud：https://iswbm.com/ucloud

有了服务器后，需要在服务器上安装 nginx

yum install nginx

然后我们在本地电脑的项目根目录下直接执行 hugo 即可编译最终的 html 文件到 public 中（记得清空此前的 public 目录，以免有缓存残留）

hugo

然后将 public 目录直接打包上传到服务器的某个目录下，这个目录自行定义即可，比如我的目录是 /home/rtd-docs/iswbm.com/public，然后直接用 nginx 进行代理即可，nginx 的配置如下

需要注意的是，在如下配置中的需要自签证书，没有搞过的请自行翻阅我之前的文章，有比较系统的讲解

server{
        listen 80;
        server_name  iswbm.com www.iswbm.com;
        return 301 https://iswbm.com$request_uri;
}

server {
        listen 443 ssl;
        server_name iswbm.com;
        index index.html;

       ssl_certificate /path/to/fullchain.pem;
       ssl_certificate_key /path/to/privkey.pem;
       ssl_trusted_certificate /path/to/cert.pem;

       root /home/rtd-docs/iswbm.com/public;
}

配置完后，直接重启 nginx，访问你的域名即可，以我的网站为例效果见下，干净简洁而且轻量，目前只整理了早期极少部分的文章，后续再花个时间慢慢搬过来

以上大概就是搭建的过程，对于大多数人来说参照本篇文章都能快速搭建，如果你在搭建过程中受阻，也可联系我v: stromwbm 交流～

参考资料

• Hugo 官方网站
• Hugo + GitHub Action，搭建你的博客自动发布系统
• hugo-theme-den 主题仓库

1、创建博客项目

1.1 准备工作

• 下载node.js并安装（官网下载安装），默认会安装npm。
• 下载安装git（官网下载安装）
• 下载安装hexo。方法：打开终端 运行npm install -g hexo（要翻墙）

1.2 初始化项目

• 新创建一个目录，比如叫做 iswbm-blog
• 使用终端进入该文件夹内，执行hexo init （初始化项目）

• 运行你的博客项目（用于调试），查看生成的文章是否符合自己的预期。

$ hexo g  # 生成静态文件
$ hexo s  # 运行本地web服务器

运行完 hexo s 会有一个本地web地址（localhost:4000）出现在你的屏幕，打开它即可看到。

1.3 部署上线

要让我们在 localhost:4000 看到的那些内容能够在公网能够访问。我们需要将其部署上线。

按照下面的步骤来

• 在Github上创建名字为XXX.github.io的项目，XXX为自己的github用户名。然后 clone 到你的本地电脑上。

  

• 打开该文件夹内的_config.yml配置文件，将其中的type设置为git，其他配置如下

# Deployment
## Docs: https://hexo.io/docs/deployment.html
deploy:
  type: git
  repository: https://github.com/iswbm/iswbm.github.io.git
  branch: master

• 安装Git部署插件

$ npm install hexo-deployer-git --save

• 重新生成静态文件，部署上线。

$ hexo clean 
$ hexo g 
$ hexo d

在第一次部署后，请到 github 后台，补充你的 网站信息，否则无法访问。

一切完成之后，你就可以通过上面的网址来访问我的博客了。

1.4 绑定域名

做为一个个人博客，使用 github的域名，明显不够个性化。

我们可以自己去阿里云购买一个域名（我的是 iswbm.com），然后将其 CNAME 到你的博客地址上。

• 去阿里云 域名云解析
  

• 然后到对应的GitHub仓库，绑定我的个性域名
  

• 然后再在你本地的项目里的 source 目录下新建 CNAME文件，内容就是我的域名

  iswbm.com
  

• 然后重新部署，使配置生效。这样就可以使用域名访问。

  $ hexo clean 
  $ hexo g 
  $ hexo d
  

2、丰富博客页面

2.1 标签页

具体请参考下官方教程：创建标签云页面

2.2 分类页面

具体请参考下官方教程：创建分类页面

2.3 关于页面

具体请参考下官方教程：创建关于页面

3、博文书写技巧

3.1 引用块

更多设置，查看官方文档

{% blockquote David Levithan, Wide Awake %}
Do not just seek happiness for yourself. Seek happiness for all. Through kindness. Through mercy.
{% endblockquote %}

效果如下

3.2 一键生成md头格式

首先在/scaffolds/post.md文件中添加：

---
title: {{ title }}
date: {{ date }}
tags:
categories: 
copyright: true
permalink: 01
top: 0
password:
---

然后使用 hexo new就可以一键生成新文章的头格式了，不用手动去搬运或者书写。相当方便。

4、美化博客

4.1 更换主题

在 hexo 部署目录下，使用如下命令下载主题

git clone https://github.com/iissnan/hexo-theme-next themes/next

打开站点配置文件（部署代码根目录下的 _config.yml）选择刚刚下载的next主题

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

然后再编辑 themes/next/_config.yml 选择主题样式

scheme: Pisces

4.2 ico缩略图

1. 制作icon图标，最好是32x32，可以在这里制作：https://tool.lu/favicon/

2. 将制作的ico文件，放到next主题source/images目录下

3. 配置ico文件路径。配置文件在 themes/next/_config.yml
favicon:
  small: /images/favicon-16x16-next.ico
  medium: /images/favicon-32x32-next.ico

4.3 菜单栏和图标

menu:
  home: / || home
  about: /about/ || user
  tags: /tags/ || tags
  categories: /categories/ || th
  archives: /archives/ || archive
  schedule: /schedule/ || calendar
  # sitemap: /sitemap.xml || sitemap
  # commonweal: /404/ || heartbeat

# Enable/Disable menu icons.
menu_icons:
  enable: true

4.4 社交网络和图标

social:
  GitHub: https://github.com/iswbm || github
  E-Mail: mailto:wongbingming@163.com || envelope-o
  微博: http://weibo.com/942663728 || weibo
  WeChat: http://image.iswbm.com/17-9-9/58657236.jpg || weixin
  知乎: https://www.zhihu.com/people/wongbingming/activities || chain-broken
  CnBlog: http://www.cnblogs.com/wongbingming/ || file-text-o
  
social_icons:
  enable: true
  icons_only: false
  transition: false

4.5 背景动画

在next下的_config.yml找到canvas_nest设置为True

4.6 添加热度

next主题集成leanCloud，我只需稍微配置下(在主题配置文件)
其中的id和key要去LeanCloud注册登录然后创建应用后，新建Class，名字一定要是Counter，然后查看id和key填入

post_meta:
  item_text: true

leancloud_visitors:
  enable: true
  app_id: 你的id
  app_key: 你的key

打开themes/next/layout/_macro/post.swig
在”leancloud-visitors-count”>标签后面添加℃。
然后打开，themes/next/languages/zh-Hans.yml，将visitors内容改为热度即可。

为什么不直接用不蒜子，因为首页的时候，无法显示。
如果也开了不蒜子的计数功能的话，可以直接把下面代码删掉

{% if not is_index and theme.busuanzi_count.enable and theme.busuanzi_count.page_pv %}
            <span class="post-meta-divider">|</span>
            <span class="page-pv">{{ theme.busuanzi_count.page_pv_header }}
            <span class="busuanzi-value" id="busuanzi_value_page_pv" ></span>{{ theme.busuanzi_count.page_pv_footer }}
            </span>
{% endif %}

如果你在前端看到了这个错误

Code 504: The app is archived, please restore in console before use.

很好解决，前往 LeanCloud 重新激活应用即可。

如果在前端又出现了这个错误

Code 403: 访问被api域名白名单拒绝，请检查你的安全域名设置.

也很好解决，前往 LeanCloud 绑定你的域名即可。不过要注意的是这个域名，你得备案，否则会绑定失败

4.7 分享插件JiaThis

默认有好多分享平台，可以在jiathis.swig里删除不需要的

jiathis:
  uid: 2135144 #Get this uid from http://www.jiathis.com/
# add_this_id:

隐藏页脚的hexo强力驱动，在footer.swig里注释这段代码

<!--
{% if theme.copyright %}
  <div class="powered-by">{#
  #}{{ __('footer.powered', '<a class="theme-link" href="https://hexo.io">Hexo</a>') }}{#
#}</div>

  <span class="post-meta-divider">|</span>
  <div class="theme-info">{#
  #}{{ __('footer.theme') }} &mdash; {#
  #}<a class="theme-link" href="https://github.com/iissnan/hexo-theme-next">{#
    #}NexT.{{ theme.scheme }}{#
  #}</a> v{{ theme.version }}{#
#}</div>
{% endif %}
-->

4.8 Fork me on Github

点击这里挑选自己喜欢的样式，并复制代码
然后粘贴刚才复制的代码到themes/next/layout/_layout.swig文件中(放在<div class="headband"></div>的下面)，并把href改为你的github地址

4.9 设置阅读全文

在md博文里添加

4.10 添加版权

修改themes/next/layout/_macro/post-copyright.swig如下

<ul class="post-copyright">
  <li class="my_post-copyright-author">
    <strong>{{ __('post.copyright.author') + __('symbol.colon') }}</strong>
    {{ config.author }}
  </li>
  <li class="my_post-copyright-link">
    <strong>本文链接：</strong>
    <a href="{{ post.permalink }}" title="{{ post.title }}">{{ post.permalink }}</a>
  </li>
  <li class="my_post-copyright-link">
    <strong>发布时间：</strong>{{ page.date.format("YYYY年MM月DD日 - HH:MM") }}
  </li>
  <li class="my_post-copyright-link">
    <strong>最后更新：</strong>{{ page.updated.format("YYYY年MM月DD日 - HH:MM") }}
  </li>

  <li class="my_post-copyright-license">
    <strong>{{ __('post.copyright.license_title') + __('symbol.colon') }} </strong>
    {{ __('post.copyright.license_content', theme.post_copyright.license_url, theme.post_copyright.license) }}
  </li>
</ul>

到主题配置文件，改enable为True

post_copyright:
  enable: true
  license: CC BY-NC-SA 3.0
  license_url: https://creativecommons.org/licenses/by-nc-sa/3.0/

4.11 文章结尾页眉

在路径themes/next/layout/_macro中新建 passage-end-tag.swig 文件,并添加以下内容：

<div>
    {% if not is_index %}
        <div style="text-align:center;color: #ccc;font-size:14px;">-------------Page's over<i class="fa fa-paw"></i>Thanks for reading-------------</div>
    {% endif %}
</div>

接着打开themes/next/layout/_macro/post.swig文件，添加如下下代码，注意位置

代码如下：

<div>
  {% if not is_index %}
    {% include 'passage-end-tag.swig' %}
  {% endif %}
</div>

然后再主题文件增加如下配置，以便可以方便开关这个功能

# 文章末尾添加“本文结束”标记
passage_end_tag:
  enabled: true

4.12 更改标签的图标

修改模板/themes/next/layout/_macro/post.swig，搜索 rel=”tag”>#，将 # 换成

<i class="fa fa-tag"></i>

4.13 添加访问量和访客数

\themes\next\layout_partials\footer.swig最前面添加如下代码

<script async src="https://dn-lbstatics.qbox.me/busuanzi/2.3/busuanzi.pure.mini.js"></script>

4.14 更改容器宽度

更改NexT容器宽度可以参考这个常见问题
Pisces Scheme比较特殊。
在themes/next/source/css/_schemes/Pisces/_layout.styl最后面增加如下样式

.header{
    width: 80%;
    +tablet() {
        width: 100%;
    }
    +mobile() {
        width: 100%;
    }
}
.container .main-inner {
    width: 80%;
    +tablet() {
        width: 100%;
    }
    +mobile() {
        width: 100%;
    }
}
.content-wrap {
    width: calc(100% - 260px);
    +tablet() {
        width: 100%;
    }
    +mobile() {
        width: 100%;
    }
}

4.15 自定义CSS

默认的博客文章，是按照你选定的主题来显示。其中可能有些并不那么尽如你意。

但是没有关系，你可以自己定义自己满意的css样式，以下是我自己定义的。在这里做个记录。

# 设置图片不居中
themes/next/source/css/_common/components/post/post-expand.styl

.post-gallery-row .fancybox img { margin: 0 auto !important;}


# 标题格式
themes/next/source/css/_common/scaffolding/base.styl

h1 {
    font-size: 27px;
    position: relative;
    padding: 15px;
    margin-bottom: 20px;
    border: 1px solid #eee;
    border-radius: 3px;
    border-left-color: red;
    border-left-width: 5px;
    background-color: #406CA4;
    color: #ffffff;
    font-family: cursive;
    border-radius: 15px 15px 15px 15px !important;
}

4.16 添加头像

将你的头像放置到 themes/next/source/images/avatar.png

在 themes/next/_config.yml 设置路径

avatar: /images/avatar.png

4.17 设置中文

在根目录的 _config.yml 里 把 language 改成 zh-Hans，这个值是要和 themes/next/languages 目录下的文件名保持一致。

4.18 不渲染 README

在根目录创建 README.md 文件，内容由你决定。

然后在 _config.yml 修改配置

skip_render: README.md

5、其他实用功能

5.1 给文章加密

打开themes->next->layout->_partials->head.swig文件,搜索pace，在这个代码块后面插入这样一段代码：

<script>
    (function(){
        if('{{ page.password }}'){
            if (prompt('请输入文章密码') !== '{{ page.password }}'){
                alert('密码错误！');
                history.back();
            }
        }
    })();
</script>

然后文章中设置

password: 你的密码

5.2 博文压缩

在站点的根目录下执行以下命令：

$ npm install gulp -g
$ npm install gulp-minify-css gulp-uglify gulp-htmlmin gulp-htmlclean gulp --save

在根目录下新建gulpfile.js

var gulp = require('gulp');
var minifycss = require('gulp-minify-css');
var uglify = require('gulp-uglify');
var htmlmin = require('gulp-htmlmin');
var htmlclean = require('gulp-htmlclean');
// 压缩 public 目录 css
gulp.task('minify-css', function() {
    return gulp.src('./public/**/*.css')
        .pipe(minifycss())
        .pipe(gulp.dest('./public'));
});
// 压缩 public 目录 html
gulp.task('minify-html', function() {
  return gulp.src('./public/**/*.html')
    .pipe(htmlclean())
    .pipe(htmlmin({
         removeComments: true,
         minifyJS: true,
         minifyCSS: true,
         minifyURLs: true,
    }))
    .pipe(gulp.dest('./public'))
});
// 压缩 public/js 目录 js
gulp.task('minify-js', function() {
    return gulp.src('./public/**/*.js')
        .pipe(uglify())
        .pipe(gulp.dest('./public'));
});
// 执行 gulp 命令时执行的任务
gulp.task('default', [
    'minify-html','minify-css','minify-js'
]);

生成博文是执行hexo g && gulp就会根据gulpfile.js中的配置，对public目录中的静态资源文件进行压缩。

5.3 设定置顶/顺序

F:\MyBlog\node_modules\hexo-generator-index\lib\generator.js改成下面

'use strict';
var pagination = require('hexo-pagination');
module.exports = function(locals){
  var config = this.config;
  var posts = locals.posts;
    posts.data = posts.data.sort(function(a, b) {
        if(a.top && b.top) { // 两篇文章top都有定义
            if(a.top == b.top) return b.date - a.date; // 若top值一样则按照文章日期降序排
            else return b.top - a.top; // 否则按照top值降序排
        }
        else if(a.top && !b.top) { // 以下是只有一篇文章top有定义，那么将有top的排在前面（这里用异或操作居然不行233）
            return -1;
        }
        else if(!a.top && b.top) {
            return 1;
        }
        else return b.date - a.date; // 都没定义按照文章日期降序排
    });
  var paginationDir = config.pagination_dir || 'page';
  return pagination('', posts, {
    perPage: config.index_generator.per_page,
    layout: ['index', 'archive'],
    format: paginationDir + '/%d/',
    data: {
      __index: true
    }
  });
};

在文章中添加 top 值，数值越大文章越靠前（默认是0，按时间排序），如

---
title: 解决Charles乱码问题
date: 2017-05-22 22:45:48
tags: 技巧
categories: 技巧
copyright: true
top: 100
---

5.5 搜索功能

参照这篇博客，搜索搜索功能

5.7 文章内链接文本样式

在F:\MyBlog\themes\next\source\css\_common\components\post\post.styl

// 文章内链接文本样式
.post-body p a{
  color: #0593d3;
  border-bottom: none;
  border-bottom: 1px solid #0593d3;
  &:hover {
    color: #fc6423;
    border-bottom: none;
    border-bottom: 1px solid #fc6423;
  }
}

其中选择.post-body 是为了不影响标题，选择 p 是为了不影响首页“阅读全文”的显示样式,颜色可以自己定义。

5.8 归档设置分页数量

在根目录的 _config.yml

index_generator:
  per_page: 5

archive_generator:
  per_page: 20
  yearly: true
  monthly: true

tag_generator:
  per_page: 10

5.9 设置永久链接

在根目录的 _config.yml

permalink: :year/:i_month/:i_day/:title.html

博文里设置一下，举个例子

permalink: Database-MySQL-Basic_usage

6、多台电脑协同更新博客

上班后，工作都会给配置了一台电脑，而自己家里也有电脑，有时候我想使用家里电脑更新博客，而有时候我也想使用公司电脑更新博客。

这就很蛋疼了，因为Markdown的原文只有一份，如何将两台电脑的原文保持一致呢。当然，容易想到的是代管在Github上。

6.1 Github上操作

将博客项目分成两个分支

• master为博客界面前端文件
• hexo 为博文markdown原文

在web界面新建分支，命名为hexo

在web界面设置 hexo 为默认分支，因为我们只会在这个分支上进行操作。

6.2 本地PC操作

clone项目到本地：

git clone git@github.com:iswbm/iswbm.github.io.git

使用 git branch 确认此时的分支是否为hexo，如果不是则上面设置默认分支有误，要重新设置。

6.3 处理hexo分支

第一步我们创建hexo分支时，hexo的内容和master的内容是完全一致的，存放的是博客前端文件，这并不是我们想要的，所以我们要先将其清空，再放入我们的文件。

清空hexo分支

git checkout --orphan hexo
git rm -rf .
git commit -m "clear hexo branch"
git push origin hexo

将博客原始文件添加进来，但是有一些是没必要放的，具体要放哪些文件，看图片。

git add -A
git commit -m "add blog markdown raw files"

添加node_modules/文件夹
本来这个文件夹，不需要拷过来的，但是怕安装 hexo-deployer-git 失败，所以之前要拷贝的。

可以从下面这个链接里获取：

下载链接；https://pan.baidu.com/s/1-DHgTuxb0mCj_7wdaKqAwQ
获取密码：pckc

然后检查是否正常渲染

hexo g
hexo s

如果一切正常，那么再确认下 _config.yml 文件的deploy参数的分支是master，我们可不能将其发布到 hexo 分支。

确认过后，我们就可以发布博客了。

hexo d

如果发布出现问题，可能是 hexo-deployer-git 这个插件安装有误，就要想办法装上了。这里就不讲了。

7、更换电脑后如何迁移博客

在真实场景里，我们会有可能会换电脑或者将系统进行重装操作，而这个时候如何将之前的电脑上项目（主要是 Markdown原文）迁移过来呢？

在七、多台电脑协同更新博客 这一节里，我们已经讲过，如何将md原文进行管理。

那就好办了呀。只要将之前的项目 clone 下来就可以了呀。

首先肯定是要在新电脑上安装Git，Node.Js，Hexo

7.1 工具安装

安装Git：百度自行下载

安装npm：到 官网 下载exe文件安装

安装hexo：执行以下命令安装（注意需要新开一个git bash窗口，不然会提示找不到npm命令）

npm install -g hexo

7.2 clone最新分支

git clone git@github.com:iswbm/iswbm.github.io.git

添加node_modules/文件夹 本来这个文件夹，不需要拷过来的，但是怕安装 hexo-deployer-git 失败，所以这里我直接备份一份，可以拷贝覆盖上即可。

下载链接；https://pan.baidu.com/s/1-DHgTuxb0mCj_7wdaKqAwQ 获取密码：pckc

完成之后，应该就可以正常更新博客了。

在写完文章后，一定要注意操作顺序。

1. 先将hexo分支push要远端
2. 再执行部署到master分支。

不然哪天这个电脑又出现故障，那就麻烦了。

参考资料

• Hexo 官方使用文档 - 中文
• Hexo Next 主题 官方使用文档 - 中文
• Hexo的next主题个性化教程：打造炫酷网站
• 使用hexo：如果换了电脑怎么更新博客？
• GitHub+Hexo 搭建个人网站详细教程
• Gitalk：基于 Github Issue 和 Preact 开发的评论插件
• Hexo搭建博客教程

以前安装 certbot 有一个叫做 certbot-auto 的脚本工具，但这个工具由于是用 python2 编写的，pythoh2 不维护后，官方也放弃了那些默认使用 python2 为默认 Python 的操作系统。

没有了那个certbot-auto，虽然会麻烦一些，但好在官方给的文档非常全，一般也不会有什么问题，具体可以去​官方查看。

下面是我在 CentOS 7.2 上的安装 方法，供你参考。

第一步：安装 snapd，并启动它。

使用 snap 对内核有要求，太老的内核版本无法使用，我的内核版本是 3.10.0-1127.el7.x86_64 供你参考

# https://snapcraft.io/docs/installing-snap-on-red-hat
sudo yum -y install snapd
sudo systemctl enable --now snapd.socket
sudo systemctl start --now snapd.socket
sudo ln -s /var/lib/snapd/snap /snap
sudo snap install core; sudo snap refresh core

第二步：使用 snap 安装 certbot（如果你在此之前有使用系统自带的包管理器安装过 certbot，那么请你先卸载它）

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

2、使用 certbot

有了 certbot 就可以用来申请证书、续费证书、部署证书了。

1、申请证书

使用如下 certbot 命令就可以开始证书的申请。以下自动完成申请，需要替换邮箱及自己的域名：

certbot --nginx --agree-tos --redirect \
        -m email@youremail.com --eff-email \
        --preferred-challenges http-01 \
        --cert-name url.com \
        -d url.com,xyz.url.com,www.url.com  -q

前提你得提前安装 nginx （这个自然不用说），安装过了但路径不对的话，需要你建立一个软链接

ln -s /usr/local/nginx/conf/ /etc/nginx

2、续期证书

certbot 的证书有效期是 3个月（准确的说应该是 90 天），这意味着你 3个月就要来处理一下续期。

续期的命令就比较简单了。

certbot renew

3、难用的 certboot

使用 cerbot 申请证书的时候，有许多交互界面需要你填入各种参数，允许各种协议，体验非常的不好。

并且最主要的是，在证书的申请和续期的过程中，有一步需要验证你对该域名的所有权，因此需要你人工登陆你域名提供商的控制台去添加类型为 txt 的 DNS 记录。

这导致了整个过程非常的繁琐，需要全程人工的界入。

而这繁琐的过程，不仅在你申请证书的时候要来一次，以后续费每次都要重复操作。

虽然各大国内域名提供商提供了 API 接口，可以让开发者调用去管理域名的 DNS 解析。

但 certbot 本身并未实现这个功能，这非常的遗憾。

4、好用的 letscertbot

但庆幸的是，certbot 的流程中保留了不少的 hook，开发者可以自行实现 DNS 的验证逻辑。

于是乎，就出现了一些有心的开发者，花时间写一些脚本，结合 certbot 来实现更多智能的工作。

在早期，有一个叫做 certbot-letencrypt-wildcardcertificates-alydns-au 在 github 项目，是基于 certbot-auto 的脚本。

之前不知道 certbot-auto 已经废弃了，让我试了半天，一直提示失败。

结果去 issue 上看，很多 issue 都没有处理，作者也已经一年没有在 github 上活跃过了。也许该项目是已经和 certbot-auto 的废弃而告终了。

于是我又开始漫天寻找新的解决方案。

终于让我找到一个叫 letscertbot 的项目。

5、使用 letscertbot

使用letscertbot 的方法有两种

1. 使用容器运行
2. 使用脚本运行

我这里使用脚本运行演示。

在开始使用之前，你需要拷贝模板配置文件，并进行配置

cp config.json.example config.json

主要配置的项有：

• base.email：填写你的邮箱，以便接收通知
• dns.aliyun：填写你的阿里云(如果你用的是阿里云域名的话)的授权id和密钥

阿里云的授权id怎么获取呢？

可前往阿里云的帮助文档：​https://help.aliyun.com/knowledge_detail/38738.html

接下来我们就可以：

1、申请证书

申请的证书全部在 /etc/letsencrypt/live/ 目录下

sudo python ./bin/obtain.py -d your.example.com *.your.example.com

2、续费证书

sudo python ./bin/renewal.py

然后你可以将该命令部署到 cron 定时任务中，这个计划任务将每七天天执行 renewal 脚本，但是七天间隔太久，最好加上 --force 参数，强制续期。

0 1 * * * $your_letscertbot_home/bin/renewal.py --force >> /var/log/letscertbot-renewal.log 2>&1

**如果你只想续期某个域名，可以加上 **--certs 参数:

sudo python ./bin/renewal.py --certs xny.example.com --force

3、部署证书

如果你将 deploy.server.enable 设置为 true, Certbot 将执行 deployment 脚本 (deploy.py) 在 deploy 钩子上。这个脚本接收到已经续期的证书并将它推送到配置好的服务器中。

Let’s Certbot 通过 SSH 为远程服务器部署证书，这意味着你执行 Certbot 的机器须通过 SSH 连接上远程服务器。为了使连接成功，你需要上传公钥到远程服务器或者提供 deploy.server.password 给 sshpass 工具。

此外，为了将证书部署到 deploy.server.deploy_to 或重启 nginx, Let’s Certbot 要求 deploy.server.user 有执行对应操作的权限。

你可以通过执行下面命令获取 deployment 脚本:

sudo python ./bin/deploy.py --check

如果需要推送证书到配置中的服务器，可以执行:

sudo python ./bin/deploy.py --push --cert $certificate_name --server $server_host

进入网站后台，设置站点地址为 https://iswbm.com

2. 设置两个 A 记录

到你的域名提供商控制台里设置两条 DNS 解析记录

3. 修改nginx配置

编辑 /usr/local/nginx/conf/nginx.conf 修改如下两个服务器配置

• 第一个配置：将 http 重定向到 https（不管带 www 还是不带 www）
• 第二个配置：接收所有的 https 请求（不管带 www 还是不带 www）

server {
        listen 80;
        server_name iswbm.com www.iswbm.com;
        return 301 https://iswbm.com$request_uri;
        }

server
    {
        listen 443 ssl;

        ssl_certificate 1_iswbm.com_bundle.pem;
        ssl_certificate_key 0_iswbm.com.key;

        server_name _;
      
        # 剩下的其他配置
    }

记得重启 nginx 使之生效。

当你在使用 https://www.iswbm.com 有可能访问不成功，因为有 301 缓存啥的，使用 F5 强制刷新就可以了。

4. 查看重定向情况

使用 curl -I url 就可以看到地址的重定向情况

$ curl -I http://iswbm.com
HTTP/1.1 301 Moved Permanently
Server: nginx
Date: Tue, 06 Jul 2021 15:34:44 GMT
Content-Type: text/html
Content-Length: 162
Connection: keep-alive
Location: https://iswbm.com/


$ curl -I https://iswbm.com
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 06 Jul 2021 15:34:48 GMT
Content-Type: text/html; charset=UTF-8
Connection: keep-alive
Vary: Accept-Encoding
X-Powered-By: PHP/7.4.9
Set-Cookie: baiduseo_data_category=%7B%22book%22%3A%22baiduseo_category%22%7D; expires=Thu, 05-Aug-2021 15:34:47 GMT; Max-Age=2592000
Set-Cookie: baiduseo_data_paymoney=%7B%22msg%22%3A1%2C%22url%22%3A%22033c2eda0b95dfc04b9c9ef1e7bb631e%22%2C%22status%22%3A1%7D; expires=Wed, 07-Jul-2021 15:34:47 GMT; Max-Age=86400
Set-Cookie: wp-editormd-lang=zh-CN; path=/
Set-Cookie: PHPSESSID=fden169bmmjbopn4rnb89c95rp; path=/
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache


$ curl -I http://www.iswbm.com
HTTP/1.1 301 Moved Permanently
Server: nginx
Date: Tue, 06 Jul 2021 15:35:03 GMT
Content-Type: text/html
Content-Length: 162
Connection: keep-alive
Location: https://iswbm.com/


$ curl -I https://www.iswbm.com
HTTP/1.1 301 Moved Permanently
Server: nginx
Date: Tue, 06 Jul 2021 15:35:08 GMT
Content-Type: text/html; charset=UTF-8
Connection: keep-alive
X-Powered-By: PHP/7.4.9
Set-Cookie: baiduseo_data_category=%7B%22book%22%3A%22baiduseo_category%22%7D; expires=Thu, 05-Aug-2021 15:35:07 GMT; Max-Age=2592000
Set-Cookie: baiduseo_data_paymoney=%7B%22msg%22%3A1%2C%22url%22%3A%22033c2eda0b95dfc04b9c9ef1e7bb631e%22%2C%22status%22%3A1%7D; expires=Wed, 07-Jul-2021 15:35:07 GMT; Max-Age=86400
Set-Cookie: wp-editormd-lang=zh-CN; path=/
Set-Cookie: PHPSESSID=0smke620aseeucca5dlbh31hhs; path=/
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
X-Redirect-By: WordPress
Location: https://iswbm.com/

5. 一个小插曲

在最开始的时候，网站后台的站点地址不小心设置错了，导致网站 都访问不了，想把地址修改回来都没办法。

真的很慌，害怕网站 就这么挂了。

不过冷静下来后，我就找到了解决方法。

方法分两步：

第一步：进入 WP 安装目录，替换目录下所有文件的域名信息

cd /home/wwwroot/wordpress/
sed -i "s/www.iswbm.com/iswbm.com/g"  `grep -r www.iswbm.com ./ -l`

第二步：进入数据库，修改数据站点地址

mysql> select * from wp_options limit 5;
+-----------+--------------------+--------------------------------------------------------------+----------+
| option_id | option_name        | option_value                                                 | autoload |
+-----------+--------------------+--------------------------------------------------------------+----------+
|         1 | siteurl            | https://www.iswbm.com                                        | yes      |
|         2 | home               | https://www.iswbm.com                                        | yes      |
|         3 | blogname           | 明哥教程                                                     | yes      |
|         4 | blogdescription    | 专注于 Python Golang Linux 云计算相关的技术分享              | yes      |
|         5 | users_can_register | 1                                                            | yes      |
+-----------+--------------------+--------------------------------------------------------------+----------+

mysql> update wp_options set option_value="https://iswbm.com" where option_id in (1,2);
Query OK, 2 rows affected (0.00 sec)
Rows matched: 2  Changed: 2  Warnings: 0

1. 准备一个域名和服务器（自行准备）
2. 并将该域名解析到你的服务器ip上
3. 生成 CSR 证书请求文件
4. 拿着 CSR 文件去申请证书
5. 把申请到的证书部署到你的服务器上

1. 设置 DNS 解析

我有一个域名 iswbm.com，其下有好多的子域名，比如写 Python 的在线博客 python.iswbm.com，还有写 Golang 的在线博客 golang.iswbm.com，还有我的图床 image.iswbm.com 等等。

这里新建了个子域名 demo.iswbm.com ，并设置其解析到 我的服务器上，如下图（服务器 ip 已码掉）。

2. 搭建 HTTP 站点

为了方便，我这里就使用 Apache 放了一个 HTTP 的静态网页，方法很简单，大家百度即可。

3. 申请 SSL 证书

SSL 数字证书怎么来的呢？

你可以自己制作，也可以向CA权威机构申请。

二者的区别是：

1. 自己颁发的证书，需要客户端验证通过，也就是需要用户手动安装证书，并将其设置为受信任的根证书。但即使如此，浏览器上（ chrome, firefox）仍不认可这种自签名证书，会在地址栏前面提示连接不安全，手动安装证书后，也会提示该证书无效。若想要继续访问，并忽略该提示，可以选择继续访问。
2. 向权威的数字证书认证机构申请，由于这些机构在网民的电脑里都有相应的根证书，且这些机构是绝对可信任的。因此你在访问网站时，不会提示连接不安全。

下面，我将分别向你展示这两种方法，都是如何操作的。

第一种：向权威CA机构申请

在阿里云和腾讯云都可以 进行 SSL 证书的申请，证书的申请有付费的（价格也不便宜），也有免费的，看了一圈，只有腾讯云有免费的 SSL 证书的申请渠道（阿里云听说以前也有，后来关闭了）。

本篇文章，仅以演示教学之用，所以只用腾讯云的免费证书的就足够啦。

登陆腾讯云，可以看到SSL 证书有分很多种，企业型的，企业型专业版的，增强型，增强型专业版的，还有域名型免费版。

点击选择 域名型免费版

点击 免费快速申请后，填写域名和你的个人邮箱

再点击下一步，会需要你验证域名所有权，验证方式有如下三种

1. 自动DNS验证
2. 手动DNS验证
3. 文件验证

但由于我的域名不是腾讯云平台解析的，因此没有 自动DNS验证的选项，只有其他两种

点击 确认申请 后，会提示你进入域名验证所有权的流程，这里我选择 手动DNS验证。

审核通过后，3s 内就会给你颁发证书，你可以从控制台点击证书下载。

下载下来的会是一个 zip 包。

解压一下，会有不同的服务器类型（有 Apache、IIS、Nginx、Tomcat）的文件夹。

我使用的是 Apache ，在这个文件夹下面有三个文件：

1. 1_root_bundle.crt：根证书
2. 2_demo.iswbm.com.crt：域名证书
3. 3_demo.iswbm.com.key：私钥文件

这三个文件，下一步会部署于我的服务器上。

接下来讲第二种 SSL 证书申请方式。

第二种：自签名的 SSL 证书

没有权威的第三方 CA 机构给自己颁发证书，那就自己给自己颁发咯。

自签名 SSL 的证书制作过程，可以分为两步：

1. 自己要当 CA 机构，那 CA 有的 CA 根证书、私钥 一样都不能少，因此第一步：生成 CA 的 crt 证书 和 CA 的私钥。
2. 要申请证书，首先服务器自己要有一个密钥对（公钥和私钥）
3. 拿着上面生成的公钥，制作一个 CSR 证书申请文件
4. 用第一步的 CA 私钥，给这个 CSR 签名，生成咱所需要的 SSL 数字证书文件。

步骤很多，命令很多，命令所带的参数更多，对于只想学习证书签发流程的你，把这些命令都背下来，并不是一个好的选择，毕竟这种事可能也干不了几次。

因此，我把这些步骤、命令，都整合成一个 shell 脚本，你只要执行这个脚本就行了。

$ bash create_self-signed-cert.sh --ssl-domain=demo.iswbm.com --ssl-trusted-domain=demo.iswbm.com --ssl-size=2048 --ssl-date=3650

对应的参数的解释，在脚本中都有解释

这个脚本过长，不好直接贴上来，我将它放在我的公众号（Python编程时光）后台，你可以直接回复『证书签名』直接获取下载。

执行完成后，会在当前目录下生成好多个文件。

其中，只有两个文件对我们有用

4. 部署 SSL 证书

根据服务器的类型不同，部署安装的方式有有所区别，腾讯云的操作文档已经非常详细了，你可以通过这个链接访问到如下的文档：https://cloud.tencent.com/document/product/400/4143

这里我将以 CentOS 7.2 + Apache 为例，演示如何部署 SSL 证书。

先安装一下 mod_ssl

$ yum install -y mod_ssl

安装完后，在 /etc/httpd/conf.d/ 目录下 会有个 ssl.conf 文件。

编辑修改这个文件，以下是我的配置供你参考

<VirtualHost 0.0.0.0:443>
     DocumentRoot "/var/www/html" 
     #填写证书名称
     ServerName demo.iswbm.com
     #启用 SSL 功能
     SSLEngine on 
     #证书文件的路径
     SSLCertificateFile /etc/pki/tls/certs/demo.iswbm.com.crt
     #私钥文件的路径
     SSLCertificateKeyFile /etc/pki/tls/private/demo.iswbm.com.key
     #根证书文件的路径
     SSLCACertificateFile /etc/pki/tls/certs/ca-bundle.crt
</VirtualHost>

如果你的证书是从权威 CA 机构上申请来的。

比如我上面从腾讯云上申请来的，那么这三个文件就是从已经从腾讯云的控制台上下载下来的那三个文件。

在修改完后，务必记得把下载的这三个文件，放到相应的目录中去。

配置完 ssl.conf，可能还需要你 check 一下 /etc/httpd/conf/httpd.conf 的一些配置，这些配置一般用默认的就可以，但是以防万一，还是写一下吧

Include conf.modules.d/*.conf

写这一行的目的，就是为了 httpd 去加载 mod_ssl 这个模块

$ cat /etc/httpd/conf.modules.d/00-ssl.conf 
LoadModule ssl_module modules/mod_ssl.so

一切配置完成后，记得重启一下 httpd 服务

$ systemctl restart httpd

然后使用 chrome 访问一下 https//demo.iswbm.com 看看，大功告成。

而如果你的证书是自签名的。

ssl.conf 配置文件下的应该改成这样

<VirtualHost 0.0.0.0:443>
     DocumentRoot "/var/www/html" 
     #填写证书名称
     ServerName demo.iswbm.com
     #启用 SSL 功能
     SSLEngine on 
     #证书文件的路径
     SSLCertificateFile /etc/pki/tls/certs/tls.crt
     #私钥文件的路径
     SSLCertificateKeyFile /etc/pki/tls/private/tls.key
</VirtualHost>

同时记得把这两个文件也拷贝到相应的目录下

$ cp tls.crt /etc/pki/tls/certs/
$ cp tls.key /etc/pki/tls/private/

最后还是不要忘了重启 httpd

$ systemctl restart httpd

试着用 chrome 访问一下，可以看到 chrome 提示该连接不安全

如果执意要访问，可以点击左下方的 继续前往，这样以后再访问的时候，就不会再出现这个警告页面了。

不安全 三个字，让人很没有安全感，那有没有办法去掉呢？

答案是，没有，只要是自签名的证书，在 chrome ，firefox 等主流浏览器看来都是不安全的。

即使你把这个根证书添加到你的受信任的证书列表中，也是徒然。

下面就试着来安装一下这个根证书。

按照下图指示，拖动证书到本地磁盘上。

打开 Mac 上的 钥匙串访问

点击 登陆，然后再拖动这个证书到窗口中进行安装

右键该证书，点击 显示简介，跳出下面的界面后，再点击 信任，把 IP 安全选择选为 始终信任。

设置完后，再访问下 demo.iswbm.com ，仍然显示连接不安全，并且证书是无效的

点击证书，显示证书，该证书确实已经放入信任列表中了。

5. 宝塔申请证书

注册并登陆宝塔（https://bt.cn），然后进入控制面板。

点击申请证书

选择免费的就好

填写你的域名后，支付订单（其实不要钱）。

然后登陆我的阿里去域名解析，根据如下提示去添加 DNS解析规则

然后静待一段时间验证成功了，就可以点击如下按钮进行下载

下载到本地后，你会得到一个 zip 包，解压一下，就可以看到证书文件及私钥。

因为我的博客使用的是 Nginx，因此我该 Nginx 下的两个文件上传到我的服务器上的 nginx 目录下.

具体怎么上传呢？你可以使用远程拷贝软件，例如 WinSCP，也可以使用 lrzsz （推荐使用）。

传到哪个目录下呢？

先使用 find 命令查找一下你的 nginx.conf 路径

$ find / -name nginx.conf
/usr/local/nginx/conf/nginx.conf

你的证书文件可以和 nginx.conf 放在同一目录下

/usr/local/nginx/conf

接下来使用 vim 编辑该文件，找到 server，添加如下行（ server 原本的内容 我使用 ... 表示，意思是不需要去动。 ）

server
    {
        listen 443 ssl;
        # 注释掉该行
				# listen 80 default_server reuseport;
			
        #证书文件名称
        ssl_certificate 1_iswbm.com_bundle.pem;
        #私钥文件名称
        ssl_certificate_key 0_iswbm.com.key;

				...
    }

尝试着登陆一下

6. 七牛去图床开启https

登陆七牛云

然后进入 证书管理 上传证书。

进入对象存储 -> 域名管理，找到 HTTPS 配置的位置，点击 修改配置。

将按钮置为开启状态，选择我们刚刚上传的证书。

设置完后，并不能立马使用

域名的升级需要一定时间，等待即可。

参考文档

• Apache 服务器证书安装
• 自签名 SSL 证书

如果你也正好有搭建个人网站的想法，那么本文会给你一个参考，也许看了这篇文章你就可以不用再百度、甚至谷歌了，因为我会写得 足够的细致而系统。

1. 写在前面

注意：文章为早期写的，iswbm.com 的站点已从 wordpress 转到当前的 hugo，下图为 wordpress 的效果

2. 准备工作

一台 Linux 服务器

在开始搭建网站之前，当然第一步是购买一个属于自己的 『服务器』。

你可以选择如下渠道进行购买：

• 阿里云
• 腾讯云
• Ucloud

等的大厂服务器，不要贪图便宜去买国外的服务器厂商，因为速度很慢很多，很影响体验。

我的就是在 阿里云 上购买的，刚开始买个最低配置的服务器就行，以后不够用了，可以慢慢升级，扩容。

可以先领个券，再购买更实惠：点击领券

今年的双11，我被阿里云邀请成为推广大使，他们给了我 100 台的免费服务器，需要的可以联系我（微信： hello-wbm），闲着也是闲着，我可以免费送给大家。

一个专属的域名

买了服务器后，你就会拥有一个公网ip，如果网站搭建起来了，你完全可以使用这个 ip 去访问，但仅供开发、测试使用。

如果要真正运营起来，想要有流量，还得搞一个域名，方便你推广。

域名的购买建议和上面服务器使用同一个厂商，可以省去一些麻烦。比如阿里云购买的域名要备案是需要你在阿里云下有一台服务器的。

一个远程登陆软件

由于后面我使用的是手工部署的方式，所以要登陆服务器进行操作。

登陆的方法有两种：

1. 厂商提供的控制台界面登陆：Workbench 和 VNC

   

   这种方法对于不经常登陆服务器运维的人来说，还是挺香的。

   

2. 自己下载专业的远程登陆软件：Xshell 或者 CRTSecure

   

在使用这些远程登陆软件时，你需要在服务器厂商控制台上面先获取到三个信息

• 服务器公网IP
• 服务器SSH端口
• 服务器远程连接密码

关于 Xshell 如何使用的，可以自行百度搜索，教程非常多。

可以到阿里云上去购买，选最低配置就足够啦，后续访问量起来了再扩容升级。

2. 部署方式选择

部署方式，可分为两种

1. 使用服务器管理软件，实现自动化部署，最著名的就是 宝塔面板 。
2. 手动登陆远程服务器，实现脚本化部署。

那么如何选择呢？

使用宝塔部署，门槛低，只要会界面点一点即可。

而使用脚本自己手工部署，需要你学会

• 远程登陆服务器：使用 Xshell 或者 直接使用厂商提供的在线SSH窗口
• 一些 Linux 的基本操作：比如 Vi/Vim 的使用，目录及文件的基本操作等

在这里建议大家跟着我使用第二种方法，也就是手工使用脚本进行部署。

原因有二：

1. 第一次接触，更精细的部署步骤会让你对 WordPress 的运作方式有更深的理解，比如使用了哪些软件，装了哪些包？
2. 自己搭建了网站，难免以后会碰到各种各样的服务器问题，尽早的接触 Linux，熟悉各项配置，对以后的运维工作会有很有帮助。

3. 部署 LNMP

3.1 什么是 LNMP

LNMP 是 Linux + Nginx + MySQL + PHP 组合的简写。

类似的组合还有：

• LAMP 的全称是 Linux + Apache + MySQL + PHP
• LNAMP 的全称是 Linux + Nginx + Apache + MySQL + PHP

其中：

• Linux 是类 Unix 计算机操作系统的统称，是目前最流行的免费操作系统。代表版本有：debian、centos、ubuntu、fedora、gentoo 等。
• Nginx 是一个高性能的 HTTP 和反向代理服务器，也是一个 IMAP/POP3/SMTP 代理服务器。
• Apache 是世界使用排名第一的Web服务器软件。 它可以运行在几乎所有广泛使用的计算机平台上，由于其跨平台和安全性被广泛使用，是最流行的Web服务器端软件之一。
• PHP 是一种在服务器端执行的嵌入 HTML 文档的脚本语言。
• MySQL 是一个关系型数据库管理系统。

这些软件一个一个安装比较费力，特别是数据库。

因此有人把这些软件的安装部署过程集成为一个 Shell 脚本，而你只要下载并执行它就可以了。简直不要太方便。

3.2 安装 LNMP

下载 LNMP 安装脚本（目前最新版本是 1.7 ，我安装的是 1.5，更多版本可查看: https://lnmp.org/download.html）

$ wget http://soft.vpser.net/lnmp/lnmp1.5.tar.gz -cO lnmp1.5.tar.gz

解压并执行它

$ tar zxf lnmp1.5.tar.gz && cd lnmp1.5 && ./install.sh lnmp

接下来会出现大量的选项，如果你不是很懂各个选项间的区别，按默认就行啦

运行脚本后，首先会让你选择数据库的版本：

没有特殊需要，建议使用默认配置，直接回车或输入序号再回车。

选好数据库，会让你设置数据库 root 用户的密码，此时如果你直接回车，会默认设置为 lnmp.org#随机数字，

在输入密码的时候，对于新手有一点注意：如果输入有错误需要删除，需要按住Ctrl再按Backspace键进行删除。

密码输好后，回车进入下一步

询问是否需要启用 MySQL InnoDB，InnoDB引擎默认为开启，一般建议开启，直接回车或输入 y 。

如果确定确实不需要该引擎可以输入 n，(MySQL 5.7+版本无法关闭InnoDB),输入完成，回车进入下一步：选择 PHP 版本，建议安装 PHP 7+的版本

回车进入下一步，选择是否安装内存优化：

可以选择不安装、Jemalloc或TCmalloc，输入对应序号回车，直接回车为默认为不安装。

如果是LNMPA或LAMP的话还会提示设置邮箱和选择Apache：

“Please enter Administrator Email Address:”，需要设置管理员邮箱，该邮箱会在报错时显示在错误页面上。再选择Apache版本：

按提示输入对应版本前面的数字序号，回车。

提示"Press any key to install…or Press Ctrl+c to cancel"后，按回车键确认开始安装。 LNMP脚本就会自动安装编译Nginx、MySQL、PHP、phpMyAdmin等软件及相关的组件。

安装时间可能会几十分钟到几个小时不等，主要是机器的配置网速等原因会造成影响。

如果显示Nginx: OK，MySQL: OK，PHP: OK

表明安装成功。

最后几行的输出

• 3306 端口是 MySQL 监听的
• 80 是 HTTP 端口
• 22 是 SSH 端口

3.3 配置 Nginx

安装好后，使用如下指令查看nginx配置文件（如果你的服务器上找不到该文件，那请使用 find / -name nginx.conf 搜索一下）

$ cat /usr/local/nginx/conf/nginx.conf

你会看到如下内容：

上图表明，安装好的nginx将网站的根目录设置为/home/wwwroot/default，这个可以根据自己的喜好进行修改。

用浏览器打开http://ip，可以看到如下内容：

其实这就是一个简单的网页demo了，自己随便修改index.html，就会有不同的内容。

4. 安装 WordPress

WordPress是使用PHP语言（这也是我们上面为什么要安装 PHP 的原因）开发的博客平台，也就是一个博客框架。

上一步安装的 LNMP，只是保证了 WordPress 的基本运行环境。

想要把你的个人网站跑起来，咱还需要安装 WordPress 。

方法也很简单，下面跟着操作就行。

第一步：安装 wordpress 安装包并解压到 /home/wwwroot

$ wget https://cn.wordpress.org/latest-zh_CN.zip && unzip latest-zh_CN.zip -d /home/wwwroot

第二步：登录MySQL（密码在前面 部署LNMP 时你设置过），创建wordpress表，创建完后输入exit退出。

$ mysql -u root -p
Enter password: 
MySQL > create database wordpress;

第三步：使用 vim 修改 nginx 配置文件（不会vim的自行百度）

$ vim /usr/local/nginx/conf/nginx.conf

找到网站根目录位置，如下图所示：

修改成如下内容：

随后，使用wq保存配置退出即可。

验证nginx是否有配置错误：

$ nginx -t

如果出现ok，successful字样，说明没有错误。没有错误，重新加载nginx：

$ nginx -s reload

修改wordpress目录权限：

$ cd /home/wwwroot && chown -R www wordpress/ && chgrp -R www wordpress/

用浏览器打开http://ip/wp-admin/setup-config.php，你可以看到如下内容：

现在就开始，进行安装。填写信息如下：

其中，*** 改为你设置的MySQL数据库密码。点击提交，出现如下内容：

在/home/wwwroot/wordpress下，创建并编写wp-config.php文件：

$ vim wp-config.php

将上图内容复制进去并wq保存退出，然后点击现在安装。最后就是配置用户信息了，这个是你登录wordpress用户后台的，要记住：

最后点击安装WordPress，安装成功会出现如下界面：

点击登录，输入账户密码，就可以登录自己的 wordpress 后台了。

这时候你使用浏览器去访问 http://ip ，就可以看到你搭建的第一个网站了。

此时你看到的这个网站，是 wordpress 默认为你安装的免费主题（应该有三个），可能并不是那么的好看，但没关系，后面我会教大家如何挑选一个自己合适的主题，把你的网站装扮得有模有样。

5. 装扮你的网站

到这里，你的网站部署已经全部完成，但是还差最后一步，也是使用 WordPress 最为核心的一步：让你的网站看起来更加专业，更加成熟。

为此我们需要做两件事：

1. 安装主题：让网站变得好看
2. 安装插件：丰富网站的功能

5.1 安装主题

同样都使用的 WordPress 的网站，外观上却天差地别。有的很酷炫，有点很简约，这是因为选了不同的主题（可以理解为皮肤）。

在你安装完 WordPress 后，本身就自带了几个免费的主题。

几乎没人会使用它们，因为实在没什么亮点（就是丑）。

在 WordPress 的自带了主题商店，里面有大量的免费主题，各式各样的都有，可能有你喜欢的。

在这里要说明一点，我的主题不是在商店里安装的，而是我通过搜索引擎找到了一个比较清爽的主题，很符合我的审美，我装扮过后的效果如下。

如果你想和我用一样的主题，我已经将安装包打包好了（需要的添加我微信领取: stromwbm），直接下载后，按下图的方式上传到你的 WordPress 后台安装就行。

5.2 安装插件

目前我安装的插件比较少，但是基本够用啦，下面列举一下，如果你有什么好插件介绍，可以评论区推荐一下：

1. WP User Avatar

原生 WordPress 默认使用 Gravatar头像，用户（包括访客评论）的头像调取都是根据所留邮箱匹配的 Gravatar 头像。

没有 Gravatar 怎么办？

只要装上 WP User Avatar 这个插件就能可以使用 WordPress 媒体库中的图片作为默认头像了。

2. WP-PostViews

安装了 WP-PostViews，就可以统计你文章的浏览次数。

需要两步配置

第一步：设置显示的文字

第二步：在你要显示的位置写入如下代码

效果如下

3. Post Views Counter

咦，上面已经安装了一个统计阅读量的插件，怎么这边又推荐一个。

上面那个统计阅读量的插件，其实做的比较粗糙。

这是什么意思。

比如同一个 ip 连续连刷10次，WP-PostViews 的阅读量会 +10，但如果你使用 Post Views Counter，这个规则可以由你来定，可以只显示一次。

安装完这个插件后，同样需要进行一些配置

为什么这里选择手动呢？

因为我发现不管在内容之前，还是在内容之后，显示的位置都比较尴尬（它会换行）。

如果你和我用一样的主题，想和我有一样的效果，那么你选择手动之后，还要按下图指示修改下代码，新增如下一段代码。

效果如下

4. WP Editor.md

或许这是一个WordPress中最好，最完美的Markdown编辑器。

可以像 md2all 和 mdnice 那样，即时显示 Markdown 的渲染效果，喜欢在后台写文章的可以安装（其实我是先本地 Typora 写好了再复制上去的）。

5. Simple Custom CSS

在修改 WordPress主题时，CSS修改是最经常用到的方法，比如调整字体、调整颜色、边距之类的都需要用到自定义的CSS代码。

虽然说 WordPress 本身提供了CSS修改的功能，不过使用起来有很多的弊端，其中最麻烦的一点就是每次更换或者更新主题之前的修改都会消失，需要重复的添加。

使用 Simple Custom CSS 这个插件可以避免这种尴尬，安装后他会在 外观 下新增一个 自定义CSS 的选项。

6. LuckyWP Table of Contents

使用我这个主题，在文章页面是没有目录索引的，对于读者来说，其实挺不方便的。

因此我安装了 LuckyWP Table of Contents，可以在我的文章中生成一个目录。目录默认是隐藏的（当然你也可以设置默认展示），需要的话再点击展开。

点击目录可以直接跳转到对应位置。

但可能是我这个主题的原因，我的网站无法跳转，如果有人知道原因，还请留言区评论一下。

7. 百度搜索推送管理

百度搜索推送管理插件是一款针对WP开发的功能非常强大的百度和Bing搜索引擎收录辅助插件。

利用该插件，站长可以快速实现百度搜索资源平台和Bing站长平台URL数据推送及网站百度收录数据查询等。

目的在于进一步提升网站的百度和Bing搜索引擎收录效率，提升网站SEO优化效果；及帮助站长通过该插件了解网站百度收录数据情况，基于数据统计参考进一步对网站内容进行调整与优化。

具体使用方法比较复杂，自己百度一下吧

8. Smart SEO Tool

Smart SEO Tool是一款专门针对WordPress开发的智能SEO优化插件，与众多WordPress的SEO插件不一样的是，Smart SEO Tool更加简单易用，帮助站长快速完成WordPress博客/网站的SEO基础优化。

我在生成 sitemap 时，报这个错误

Google 了半天，网上说的解决方法有很多，但是好像对我没啥用。

最后我无意中发现在你的主题目录下的 functions.php 文件最后多了很多空格，于是就把这些空格给清理了下，没想到还真的好了。

6. 优化你的网站

6.1 使用固定链接

先在后台按如下图示进行设置

但是这样不够，要使用固定链接，服务器还需要开启 rewrite 的功能。

如果你和我使用的是 nginx ，那么只要登陆服务器，在

/usr/local/nginx/conf/nginx.conf 里的 server 里加上这一段（我放在倒数第二段）

location / {
		if (!-e $request_filename) {
				rewrite (.*) /index.php;
		}
}

然后重启一下 nginx

$ systemctl restart nginx

6.2 网站添加备案号

如果你的域名已经备案了，最好将你的备案号放到底部（好像会有检查）。

6.3 美化文章的排版

一个好的排版，能够极大提升阅读体验，因此定制一个好的排版非常有必要。

#write a.md-toc-inner {
    line-height: 1.6;
    white-space: pre-line;
    border-bottom: none;
}

#write a:hover {
    border-bottom: 2px solid #f22f27;
    color: #cc1616;
}

h1,
h2,
h3,
h4,
h5,
h6 {
    position: relative;
    margin-top: 1rem;
    margin-bottom: 1rem;
    font-weight: bold;
    line-height: 1.4;
    cursor: text;
}

h1:hover a.anchor,
h2:hover a.anchor,
h3:hover a.anchor,
h4:hover a.anchor,
h5:hover a.anchor,
h6:hover a.anchor {
    text-decoration: none;
}

h1 tt,
h1 code {
    font-size: inherit !important;
}

h2 tt,
h2 code {
    font-size: inherit !important;
}

h2.uptop {
	border-bottom: 1px green;
}


.uptop::before {
    content: ' '!important;
    color: #f22f27;
}

h3 tt,
h3 code {
    font-size: inherit !important;
}

h4 tt,
h4 code {
    font-size: inherit !important;
}

h5 tt,
h5 code {
    font-size: inherit !important;
}

h6 tt,
h6 code {
    font-size: inherit !important;
}

h2 a,
h3 a {
    color: #34495e;
}


h2 {
    margin: 2em auto 1.4em;
    /* padding-left: 10px; */
    /* display:inline-block; */
    line-height: 1.4;
    font-size: 1.8em;
    /* border-left: 9px solid var(--main-6); */
    /* border-bottom: 1px solid #ddd; */
    border-bottom: 1px solid #f22f27;
}

h2::before {
    content: '# '!important;
    color: #f22f27;
}

h3 {
    font-size: 1.4em;
    line-height: 1.43;
    margin: 1.6em auto 1.2em;
    padding-left: 9px;
    border-left: 5px solid #f22f27;
}


/* 三级四级标题点击后左边的提示图标 */

#write>h3.md-focus:before,



/* 引用文字 */
.view-content blockquote p {
    color: #353535;
    font-size: 16px;
    margin: 0 10px;
    display: block;
}

.view-content .blockquote:after {
    content: "”";
    float: right;
    display: block;
    font-size: 2em;
    color: rgb(248, 57, 41);
    font-family: Arial, serif;
    line-height: 1em;
    font-weight: 700;
}

/* 二维码显示 */
header .gongzhonghao {
    color: #fff;
    font-size: 14px;
    position: absolute;
    bottom: 30px;
}

header .weixinhao {
    color: #fff;
    font-size: 14px;
    position: absolute;
    bottom: 180px;
}


/* 表格样式 */
table {
    padding: 0;
    word-break: initial;
}

table tr {
    border-top: 1px #f22f27;
    margin: 0;
    padding: 0;
}

table tr:nth-child(2n),
thead {
    background-color: #fafafa;
}

table tr th {
    font-weight: bold;
    border: 1px solid #f22f27;
    border-bottom: 0;
    text-align: left;
    margin: 0;
    padding: 6px 13px;
}

table tr td {
    border: 1px solid #f22f27;
    text-align: left;
    margin: 0;
    padding: 6px 13px;
}

table tr th:first-child,
table tr td:first-child {
    margin-top: 0;
}

table tr th:last-child,
table tr td:last-child {
    margin-bottom: 0;
}

/* 代码框 */
#write .md-fences {
    border: 1px solid #7a7a7a;
    -webkit-font-smoothing: initial;
    margin: 2rem 0 !important;
    /* padding: 0.3rem 0 !important; */
    padding: 3px 5px;
    line-height: 1.55rem;
    border-radius: 10px;
    font-family: 'Roboto Mono', 'Source Sans Pro', 'Microsoft YaHei', '微软雅黑' !important;
    font-size: 0.9rem;
    word-wrap: normal;
}

#write [mdtype="math_block"] {
    font-size: 1.2rem;
}

#write .CodeMirror-wrap .CodeMirror-code pre {
    padding-left: 12px;
    line-height: 1.55rem;
}

.cm-s-inner .CodeMirror-linenumber {
    width: 2ch !important;
    color: rgba(128, 128, 255, 0.8);
}

#write .CodeMirror-cursors .CodeMirror-cursor {
    border-left: 2px solid #ff887a;
}

进入 WP Editor.md 插件配置文章的 markdown 渲染：

第一：开启目录

安装完 Table of Contents Plus 插件后，可以设置目录的显示位置

第二：设置代码主题

6.4 部署 HTTPS

关于如何部署 HTTPS ，我在之前的文章里讲过一种。

今天再介绍另外一种：使用宝塔。

注册并登陆宝塔（https://bt.cn），然后进入控制面板，进行实名认证。

点击申请证书

选择免费的就好

填写你的域名后，支付订单（其实不要钱）。

然后点击详情，需要验证该域名是归你所有。

方法它会告诉你，登陆我的阿里云域名解析，根据如下提示去添加 DNS解析规则

然后静待一段时间验证成功了，就可以点击如下按钮，下载数据证书。

下载到本地后，你会得到一个 zip 包，解压一下，就可以看到证书文件及私钥。

因为我的博客使用的是 Nginx，因此我该 Nginx 下的两个文件上传到我的服务器上的 nginx 目录下.

具体怎么上传呢？你可以使用远程拷贝软件，例如 WinSCP，也可以使用 lrzsz （推荐使用）。

传到哪个目录下呢？

先使用 find 命令查找一下你的 nginx.conf 路径

$ find / -name nginx.conf
/usr/local/nginx/conf/nginx.conf

你的证书文件可以和 nginx.conf 放在同一目录下

/usr/local/nginx/conf

接下来使用 vim 编辑该文件，找到 server，添加如下行（ server 原本的内容 我使用 ... 表示，意思是不需要去动。 ）

server
    {
        listen 443 ssl;
        # 注释掉该行
				# listen 80 default_server reuseport;

        #证书文件名称
        ssl_certificate 1_iswbm.com_bundle.pem;
        #私钥文件名称
        ssl_certificate_key 0_iswbm.com.key;

				...
    }

最后重启 nginx

$ systemctl restart nginx

尝试用 https 访问一下我的网站 https://iswbm.com，非常顺利。

到这里，事情其实还没有结束，你还需要做两件事情：

第一件事：在后台进行一些配置，不然从网站跳转的时候还是会使用 http

第二件事：将 http 重定向到你 https，不然有人在浏览器输入 iswbm.com 时，访问的还是 http。

使用 vim 编辑 /usr/local/nginx/conf/nginx.conf，在原本 server 的前面加入下面这么一段代码

server {
        listen 80;
        server_name iswbm.com;
        rewrite ^(.*) https://$server_name$1 permanent;
        }

然后再重启 nginx

$ systemctl restart nginx

6.5 图床开启HTTPS

由于我之前的 markdown 文章，使用的图床都是 七牛云，当时并没有开启 https，现在网站开启了 https 后，自然图片也要开启，不然浏览器会显示有部分不安全的资源。

登陆七牛云，然后进入 证书管理 上传证书（注意这个证书得另外申请，不能使用先前申请的 iswbm.com 证书）。

进入对象存储 -> 域名管理，找到 HTTPS 配置的位置，点击 修改配置。

将按钮置为开启状态，选择我们刚刚上传的证书。

设置完后，并不能立马使用

域名的升级需要一定时间，等待即可。

以上就是我搭建网站的全部总结，写了两个晚上，直到昨晚才完成。

关注我时间长点的读者，都知道我除了维护一个个人技术博客之外，还有写过很多实用的在线文档。

这些文档，都有一个痛病，他们都是静态网站，因此没有评论区。

而对于博客来说，评论区是增强技术交流的一个重要工具，文档若有事实错误和描述性问题，读者就没法方便地向我反馈。

对于动态网站来说，可以动手设计一个评论管理系统，虽然可以做，但也并不是一件易事，要做用户的管理（包括注册、登陆），库表的设计、多级回复等等

而静态网站没有数据库，若想提供评论功能，通常的做法是直接使用现成的评论插件，界面美观还易用。

我了解过的评论系统有：

• 国内：有言（官网已经挂了）、畅言（搜狐出品）
• 国外：Disqus（被墙）、gitment、gitalk、来比力（速度很慢）

其中 gitment 和 gitalk 的原理类似，都是将评论内容存储在 github 仓库的 issue 中。

我挑了知名度较高的 gitalk 部署了下，当我访问文档时，才发现这货居然，要我手动为每篇文章仓库一个 issue？

这对于一个还没有多少文章的新站点来说，可能还不是什么问题，可是我的 5、6 年的文章，有上千篇，一个一个去手动创建，这是不可能的。

于是我就开始找自动化脚本，其中有 ruby 的，python 的，方案特别多，看得我眼花缭乱的。

最终在某个 Python 脚本作者的方案中，看到了这么一句话

好家伙，刚部署完一个，又让我部署另一个。

不过 utterances 不用自动为每篇文章创建 issue，这个正是我需要的。

因此本篇文章是基于 utterances 插件的评论系统接入 Sphinx 文档的教程

若你之前有跟着我的教程搭建过 Sphinx 在线技术文档，可以跟着操作一下，因为我搜索了下，本篇应该是第一篇有公开的 Sphinx 接入 utterances评论系统的教程（也许有人使用过，但没人分享过文章）。

2. 安装 utterances

访问 utterances 应用程序 ，然后点击 Install 按钮进行安装

在安装时，可以立即选择是否限制其访问的仓库，若安装时忘记设置了，也可以在安装后再次选择。

只要再次访问 utterances 应用程序，就会显示配置的界面

点进去就能更新配置，选择完直接 Save 。

3. 定义评论模板

我的文档使用的是 Sphinx + rtd 主题，因此找到 sphinx_rtd_theme 所在的目录，比如我的目录是 /usr/local/lib/python3.6/site-packages/sphinx_rtd_theme

在该目录下新建 comments.html 文件，内容如下

<comments>
  <script src="https://utteranc.es/client.js"
    repo="iswbm/magic-python"
    issue-term="pathname"
    theme="github-light"
    crossorigin="anonymous"
    async>
  </script>
</comments>

其中你需要根据自己的情况进行调整的字段只有 repo，填写你评论要存放在哪个 github 仓库。

定义了 comments 的模板文件后，要在 layout.html 中引用它

但由于原先 layout.html 已经预留了 comments 的内容，先将其删除

替换成

         <div class="articleComments">
               {% include "comments.html" %}
           </div>

4. 编译查看效果

执行 make html 重新编译文档的静态 html 文件，再次查看网页，就会发现在文档的尾部出现了期待的评论区

想要在文章下评论，就得先登陆 Github 授权一下

登陆并授权之后，你的 Github 头像出现了，是可以评论的状态

utterances 的评论是放在 issue 里的，因此评论这边也是要支持 markdown

写完之后，点下预览可以看下效果

没什么问题的话，可以点击 comment 发送评论

评论就会出现在上方，这个布局有点迷呆，怎么不是在下方？

去 Github 仓库的 issue 上看，确实是多了一条信息

5. 总结一下

utterances 与 gitalk 对比一下，缺点不少，比如：

• gitalk 可以通过 如下容器定义评论区的位置，而 utterances 则不行（反正我没有找到对应方法），需要你有动手能力去定义模板。
• utterances 不支持在评论区直接引用他人的评论进行多级回复
• 当有评论时 utterances 的评论框是在所有的评论的下方，不太符合用户逻辑

即使 utterances 有如此之多的缺点，但 utterances 不需要手动去创建 issue ，仅凭这一点，在我看来，就可以秒杀 gitalk ，希望 gitalk 早日改进支持吧。

它可以帮我们收集网站访问数据，提供流量趋势、来源分析、转化跟踪、页面热力图、访问流等多种统计分析服务。

首先使用你的百度帐号登陆 百度统计。

然后在网站列表新增一个你的网站，我的信息如下：

填写完成，就可以获取一段属于你的网站的专属 js 代码（下面第一步）。

第二步内容，是教你如何安装这段 js 代码。

将这段代码内容写入一个单独的 js 文件：baidutongji.js

var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "https://hm.baidu.com/hm.js?xxxxxxxx";
  var s = document.getElementsByTagName("script")[0]; 
  s.parentNode.insertBefore(hm, s);
})();

并修改 conf.py 后，提交至你的 Github。

html_js_files = [
    'js/readmore.js',
    'js/baidutongji.js'
]

一切完成后，就可以去 readthedocs 重建构建。构建完成后，去执行第三步，代码安装检查。像我下面这样，就是安装完成了。

这个插件安装完成后，如果你的网站有流量，可以过个一个小时，点击一下查看报告查看你网站的详细访问数据。

数据真的非常全面，你可以知道，访客都是从哪里访问（直接访问，Google等），每篇文章的点击量（你就知道哪篇是爆款？），每天有多少老访客，多少新访客等等，更多维度的数据你可以自己去查看下。

但在本地使用 make html 构建生成的 html ，是没有这个的。由于我一直使用 RTD 进行托管，对于这个差异也没有必要去关心了。

可是最近我在搞 SEO 往 Google 上提交站点的 sitemap 时，发现往 Sphinx 项目中加入 sphinx-sitemap 插件后，再使用 RTD 的时候生成的 sitemap 是有问题的，主站的 sitemap 仅有几个版本分支的 url，文章的 url 一个都没有。

但是在本地使用 make html 又是没有问题的，这让我非常的困惑，但又没有办法，毕竟我无法对 RTD 的构建过程进行调试。

于是我只能放弃 RTD 的托管，而改用本地构建，并把构建好的 HTML 放到自己的服务器上，使用 NGINX 进行代理，对外提供访问服务。

但是使用本地构建，我又得放弃 RTD 提供的多版本切换边栏，这也让我不能接受。

原因是在我的 《PyCharm中文指南》在线文档中，有分 windows 版本和 mac 版本的文档，对于不同的人需要看不同版本的。

如果在界面上提供这个入口的话，那么有很多人就不知道怎么切换了。

于是乎，我就在网络上，找了各种 Sphinx 支持本地构建插入 RTD Theme 的 multi-version sidebar。

在网上能找到的插件有两个：

1. sphinxcontrib-versioning
2. sphinx-multiversion

其中 sphinxcontrib-versioning 是 N 多年前的项目了，我在本地使用报各种报错，去 github 上一看，发现这个仓库如今已经没人维护了，在 github 一堆 issue 没人解决。

最后只能把希望寄托在 sphinx-multiversion 上面。在验证 sphinx-multiversion 的过程中，实际上也遇到了不少问题，花了不少时间，直到昨天晚上才把流程跑通。

下面来分享下经过整理精简过的教程，如果你刚好有需要，可以参考下。

1. 安装插件

使用 pip 安装 sphinx-multiversion 插件

$ pip3 install sphinx-multiversion

并把该依赖库写入到 requirements.txt 文件中

echo "sphinx-multiversion==0.2.4" >>requirements.txt

并且该插件追加到 Sphinx 的配置文件中的 extensions 中

extensions = ['chinese_search','sphinx.ext.mathjax','sphinx_sitemap', 'sphinx_multiversion']

2. 使用插件

使用 sphinx-multiversion 帮你做的其实就是把你设定好的 html 模板渲染好写入每一个生成的 html 的文件中。

因此 ，在用它之前，你首先得写好你的模板，在这里由于我们要使用 RTD Theme 的样式，所以你得找到这样的现成的样式，在官方文档上刚好有 share，我直接搬过来了。

{%- if current_version %}
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
  <span class="rst-current-version" data-toggle="rst-current-version">
    <span class="fa fa-book"> Other Versions</span>
    v: {{ current_version.name }}
    <span class="fa fa-caret-down"></span>
  </span>
  <div class="rst-other-versions">
    {%- if versions.tags %}
    <dl>
      <dt>Tags</dt>
      {%- for item in versions.tags %}
      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
      {%- endfor %}
    </dl>
    {%- endif %}
    {%- if versions.branches %}
    <dl>
      <dt>Branches</dt>
      {%- for item in versions.branches %}
      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
      {%- endfor %}
    </dl>
    {%- endif %}
  </div>
</div>
{%- endif %}

这个文件可以放在与 conf.py 同级目录下的 _templates 目录，文件名为 versions.html，如果你先前没有该目录，需要你手动创建它。

$ cd source
$ mkdir _templates

接下来，你得在 conf.py 中写几个配置，告诉 Sphinx 去哪里找到这个 versions.html

templates_path = ['_templates']
html_sidebars = {
    '**': [
        'versioning.html',
    ],
}

# 指定哪个分支为 lastest 版本
smv_latest_version = 'master'

接下来就可以使用 sphinx-multiversion 提供的 cli 命令去构建多版本的 html 了。

$ sphinx-multiversion source build/html

其中两个参数的意义是：

• source：表示 md 或 rst 文档所在的目录，一般是 conf.py 所在目录
• build/html：表示你要将构建好的 html 放在哪个目录下

执行后，会在 build/html 目录下生成多个目录，每一个目录是一个版本。

 $ ls -l build/html/
drwxr-xr-x 19 root root   4096 Jul  9 01:31 master
drwxr-xr-x 19 root root   4096 Jul  9 00:39 v1.0
drwxr-xr-x 19 root root   4096 Jul  9 00:39 v2.0
drwxr-xr-x 19 root root   4096 Jul  9 00:39 v3.0

最后一步，就配置 nginx 代理，并重启 nginx

server {
        listen 80;
        server_name magic.iswbm.com;
        root /home/wwwroot/magic-python/build/html/;
        }

如此一来，以后访问在线文档的三个版本就得使用如下三个 url：

• http://magic.iswbm.com/master
• http://magic.iswbm.com/v1.0
• http://magic.iswbm.com/v2.0

是不是我还不错呢？

不过这还不够，访问最新版本的时候，不应该还使用 http://magic.iswbm.com/master，而应该还是根目录 http://magic.iswbm.com

那怎么办呢？

我想到的办法是把 master 目录里的文件及文件夹，全部拷贝一份到 与 master 同级目录下（如果你有更好的办法，请一定留言告诉我）。

因此最后的构建命令变成了这样

rm -rf build/ && sphinx-multiversion source build/html && cp -rf build/html/master/* build/html/

为了方便，我为这条命令定义了别名 rebuild，这样以后要构建只要执行 rebuild 即可

$ echo "alias rebuild='rm -rf build/ && sphinx-multiversion source build/html && cp -rf build/html/master/* build/html/'" >> /root/.bash_profile
$ source /root/.bash_profile

写博客的平台有很多，CSDN，博客园，51CTO，还有人会使用Hexo+GitHub，WordPress，比较会折腾的人还会自己使用Java，Python搭建，我就干过这样的事，不过每年还要支付域名和服务器，比较麻烦而且浪费钱。

以上博客我都有注册使用过，不过最终还是放弃。博客文章，比较零散，无法形成一个系统性的知识体系，不便索引。

为了使自己的文章能有一个比较完整的体系。经过一番探索之后，能满足我的基本要求的有如下两种：

• GitHub Wiki，适合做知识整理，但排版一般，不方便查看。
• GitBook，样式不好看，访问速度慢。

由于以上两种都有各自的不足的地方，所以我最后选择了一个完美的解决方案：Markdown+Pandoc+Sphinx+GitHub+ReadtheDocs
来管理我的文章。

• Markdown：书写文档
• Pandoc：格式转化
• Sphinx：生成网页
• GitHub：托管项目
• ReadtheDocs：发布网页

1. 成品展示

以我的博客(python.iswbm.com)为例，先给大家展示一下。

这是首页。显示了你所有的文章索引。

这是我的导航栏。是不是结构很清晰，很方便索引。

点击文章后，还可以很方便查看标题，跳转。

体验下搜索功能，速度很快。

看完这些你是不是也很想拥有这样一个博客呢？

只要你认真往下看，30分钟搭建这样一个博客不在话下。

2. 安装Sphinx

安装之前，请确认下Python版本。我这里使用的是Python 2.7.14，其他版本请自行尝试噢，Python3.6好像有些坑，你需要踩一下。

安装Python工具包

$ pip install sphinx sphinx-autobuild sphinx_rtd_theme -i https://pypi.douban.com/simple/

初始化

# 先创建一个工程目录:F:\mkdocs
$ cd F:\mkdocs

$ sphinx-quickstart

执行这个命令sphinx-quickstart的时候，会让你输入配置。除了这几个个性化配置，其他的都可以按照默认的来。

> Project name: MING's BLOG
> Author name(s): MING
> Project release []: 1.0
> Project language [en]: zh_CN

完了后，就可以看见创建的工程文件。

F:\mkdocs
(mkdocs) λ ls -l
total 5
-rw-r--r-- 1 wangbm 1049089 610 Jun 23 16:57 Makefile
drwxr-xr-x 1 wangbm 1049089   0 Jun 23 16:57 build/
-rw-r--r-- 1 wangbm 1049089 817 Jun 23 16:57 make.bat
drwxr-xr-x 1 wangbm 1049089   0 Jun 23 16:57 source/

F:\mkdocs
(mkdocs) λ tree
卷 文档 的文件夹 PATH 列表
卷序列号为 0002-B4B9
F:.
├─build
└─source
    ├─_static
    └─_templates

解释下这些文件/夹：

• build：文件夹，当你执行make html的时候，生成的html静态文件都存放在这里。
• source：文件夹：你的文档源文件全部应全部放在source根目录下。
• Makefile：编译文件。完全不用管。
• make.bat：bat脚本。你也不用管。

3. 配置及扩展

Sphinx 的配置文件是 source\conifg.py

由于修改的内容比较多而杂，为了使这个搭建过程，更加顺畅。

小明已经给你精心准备了一份配置文件。你只要关注我的公众号「Python编程时光」，后台直接回复 「Sphinx」即可获取。

关于配置文件，我做了哪些事：

• 配置主题
• 支持LaTeX
• 支持中文检索

以上配置文件，需要搭配扩展模块才能使用。扩展模块同样我也给你准备好了，在你回复「Sphinx」后，获取压缩包后，里面有个 exts 文件夹。你只要将这个文件夹原封不动的放置在与source的同级目录下即可。

由于扩展模块会用到一些第三方依赖包，需要你去包装它。requirements.txt 同样我也给你准备好了，在压缩包里有。

你只要执行这个命令，即可安装。

pip install -r requirements.txt -i https://pypi.douban.com/simple/

4. 撰写文章

万事俱备，接下来要写文档了。

在source目录下，新增文件 how_to_be_a_rich_man.rst（至于什么是rst格式呢，请自行搜索引擎噢）

文件内容如下

第一章 如何成为有钱人
======================

1.1 财富继承法
---------------------

有个有钱的老爸。


1.2 财富共享法
---------------------

有个有钱的老婆。

写好文档后，千万记得要把这个文档写进，目录排版里面。

排版配置文件是 source\index.rst，千万要注意中间的空行不可忽略。

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   how_to_be_a_rich_man

然后删除这几行吧，没啥用。

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

然后执行make html 生成html静态文件。

F:\mkdocs
(mkdocs) λ make html
Running Sphinx v1.7.4
loading translations [zh_CN]... done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 2 source files that are out of date
updating environment: [extensions changed] 2 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

The HTML pages are in build\html.

执行完了后，你可以发现原先的build，不再是空文件夹了。

我们点进去 build\html\ 目录，使用浏览器打开index.html文件。

真棒，已经完成了一半了。点击 我们刚写的 暴富指南。

5. 托管项目

看到网页的那一刻是不是相当激动。

不过别激动，这只是本地的，我们需要将其发布在线上。

这里我将工程文件，托管在GitHub上，然后由Read the Docs发布。

在托管之前呢，我们需要准备工作。在mkdocs根目录下，添加文件.gitignore（聪明的你，肯定知道这是什么），内容如下

build/
.idea/
*.pyc

接下来，在你的GitHub上新建一个仓库。然后把mkdocs这个目录下的所有文件都提交上去。步骤很简单，这里就不细讲了。

6. 发布上线

托管完成后，我们要发布它，让别人也可以使用公网访问。

你需要先去 Read the Docs 注册下帐号。

关联一下GitHub

导入代码库。填好与你对应的信息。

构建网页后。右下方，你可以看见你的在线地址。

这里要提醒一下的是，Sphinx的文档格式，默认是 rst 格式，如果你习惯了使用Markdown来写文章，可以使用 Pandoc 这个神器转换一下。

这里给出格式转换命令。

pandoc -V mainfont="SimSun" -f markdown -t rst hello.md -o hello.rst

或者你也可以在 Sphinx 上添加支持 Markdown 渲染的扩展模块。这需要你自己去折腾了。

到这里，属于你的个人博客就搭建好了，快去试一下吧。

附录：参考文档

• Sphinx配置MarkDown解析
• Sphinx使用手册(部分汉化)
• 搭建参考文章
• Sphinx conf.py 配置详解

这个库可以帮你做什么呢 ？

其实很简单，就是可以帮你更方便地写python装饰器代码，更重要的是，它让 Python 中被装饰器装饰后的方法长得更像装饰前的方法。

本篇文章不会过多的向你介绍装饰器的基本知识，我会默认你知道什么是装饰器，并且懂得如何写一个简单的装饰器。

不了解装饰器的可以先去阅读我之前写的文章，非常全且详细的介绍了装饰器的各种实现方法。

常规的装饰器

下面这是一个最简单的装饰器示例，在运行 myfunc 函数的前后都会打印一条日志。

def deco(func):
    def wrapper(*args, **kw):
        print("Ready to run task")
        func(*args, **kw)
        print("Successful to run task")
    return wrapper

@deco
def myfunc():
    print("Running the task")

myfunc()

装饰器使用起来，似乎有些高端和魔幻，对于一些重复性的功能，往往我们会封装成一个装饰器函数。

在定义一个装饰器的时候，我们都需要像上面一样机械性的写一个嵌套的函数，对装饰器原理理解不深的初学者，往往过段时间就会忘记如何定义装饰器。

有一些比较聪明的同学，会利用 PyCharm 来自动生成装饰器模板

然后要使用的时候，直接敲入 deco 就会生成一个简单的生成器代码，提高编码的准备效率

使用神库

使用 PyCharm 的 Live Template ，虽然能降低编写装饰器的难度，但却要依赖 PyCharm 这一专业的代码编辑器。

这里，明哥要教你一个更加简单的方法，使用这个方法呢，你需要先安装一个库 ： decorator，使用 pip 可以很轻易地去安装它

$ python3 -m pip install decorator

从库的名称不难看出，这是一个专门用来解决装饰器问题的第三方库。

有了它之后，你会惊奇的发现，以后自己定义的装饰器，就再也不需要写嵌套的函数了

from decorator import decorator

@decorator
def deco(func, *args, **kw):
    print("Ready to run task")
    func(*args, **kw)
    print("Successful to run task")

@deco
def myfunc():
    print("Running the task")

myfunc()

deco 作为装饰函数，第一个参数是固定的，都是指被装饰函数，而后面的参数都固定使用 可变参数 *args 和 **kw 的写法，代码被装饰函数的原参数。

这种写法，不得不说，更加符合直觉，代码的逻辑也更容易理解。

带参数的装饰器

装饰器根据有没有携带参数，可以分为两种

第一种：不带参数，最简单的示例，上面已经举例

def decorator(func):
    def wrapper(*args, **kw):
        func(*args, **kw)
    return wrapper

第二种：带参数，这就相对复杂了，理解起来了也不是那么容易。

def decorator(arg1, arg2):
    def wrapper(func):
        def deco(*args, **kwargs)
            func(*args, **kwargs)
        return deco
    return wrapper

那么对于需要带参数的装饰器，decorator 是否也一样能很好的支持呢？

下面是一个官方的示例

from decorator import decorator

@decorator
def warn_slow(func, timelimit=60, *args, **kw):
    t0 = time.time()
    result = func(*args, **kw)
    dt = time.time() - t0
    if dt > timelimit:
        logging.warn('%s took %d seconds', func.__name__, dt)
    else:
        logging.info('%s took %d seconds', func.__name__, dt)
    return result
  
@warn_slow(timelimit=600)  # warn if it takes more than 10 minutes
def run_calculation(tempdir, outdir):
    pass

可以看到

• 装饰函数的第一个参数，还是被装饰器 func ，这个跟之前一样
• 而第二个参数 timelimit 写成了位置参数的写法，并且有默认值
• 再往后，就还是跟原来一样使用了可变参数的写法

不难推断，只要你在装饰函数中第二个参数开始，使用了非可变参数的写法，这些参数就可以做为装饰器调用时的参数。

签名问题有解决？

我们在自己写装饰器的时候，通常都会顺手加上一个叫 functools.wraps 的装饰器，我想你应该也经常见过，那他有啥用呢？

先来看一个例子

def wrapper(func):
    def inner_function():
        pass
    return inner_function

@wrapper
def wrapped():
    pass

print(wrapped.__name__)
#inner_function

为什么会这样子？不是应该返回 func 吗？

这也不难理解，因为上边执行func 和下边 decorator(func) 是等价的，所以上面 func.__name__ 是等价于下面decorator(func).__name__ 的，那当然名字是 inner_function

def wrapper(func):
    def inner_function():
        pass
    return inner_function

def wrapped():
    pass

print(wrapper(wrapped).__name__)
#inner_function

目前，我们可以看到当一个函数被装饰器装饰过后，它的签名信息会发生变化（譬如上面看到的函数名）

那如何避免这种情况的产生？

解决方案就是使用我们前面所说的 functools .wraps 装饰器。

它的作用就是将 被修饰的函数(wrapped) 的一些属性值赋值给 修饰器函数(wrapper) ，最终让属性的显示更符合我们的直觉。

from functools import wraps

def wrapper(func):
    @wraps(func)
    def inner_function():
        pass
    return inner_function

@wrapper
def wrapped():
    pass

print(wrapped.__name__)
# wrapped

那么问题就来了，我们使用了 decorator 之后，是否还会存在这种签名的问题呢？

写个例子来验证一下就知道啦

from decorator import decorator

@decorator
def deco(func, *args, **kw):
    print("Ready to run task")
    func(*args, **kw)
    print("Successful to run task")

@deco
def myfunc():
    print("Running the task")

print(myfunc.__name__)

输出的结果是 myfunc，说明 decorator 已经默认帮我们处理了一切可预见的问题。

总结一下

decorator 是一个提高装饰器编码效率的第三方库，它适用于对装饰器原理感到困惑的新手，可以让你很轻易的写出更符合人类直觉的代码。对于带参数装饰器的定义，是非常复杂的，它需要要写多层的嵌套函数，并且需要你熟悉各个参数的传递路径，才能保证你写出来的装饰器可以正常使用。这时候，只要用上 decorator 这个库，你就可以很轻松的写出一个带参数的装饰器。同时你也不用担心他会出现签名问题，这些它都为你妥善的处理好了。

这么棒的一个库，推荐你使用起来。

这个库可以帮你做什么呢 ？

其实很简单，就是可以帮你更方便地写python装饰器代码，更重要的是，它让 Python 中被装饰器装饰后的方法长得更像装饰前的方法。

本篇文章不会过多的向你介绍装饰器的基本知识，我会默认你知道什么是装饰器，并且懂得如何写一个简单的装饰器。

不了解装饰器的可以先去阅读我之前写的文章，非常全且详细的介绍了装饰器的各种实现方法。

常规的装饰器

下面这是一个最简单的装饰器示例，在运行 myfunc 函数的前后都会打印一条日志。

def deco(func):
    def wrapper(*args, **kw):
        print("Ready to run task")
        func(*args, **kw)
        print("Successful to run task")
    return wrapper

@deco
def myfunc():
    print("Running the task")

myfunc()

装饰器使用起来，似乎有些高端和魔幻，对于一些重复性的功能，往往我们会封装成一个装饰器函数。

在定义一个装饰器的时候，我们都需要像上面一样机械性的写一个嵌套的函数，对装饰器原理理解不深的初学者，往往过段时间就会忘记如何定义装饰器。

有一些比较聪明的同学，会利用 PyCharm 来自动生成装饰器模板

然后要使用的时候，直接敲入 deco 就会生成一个简单的生成器代码，提高编码的准备效率

使用神库

使用 PyCharm 的 Live Template ，虽然能降低编写装饰器的难度，但却要依赖 PyCharm 这一专业的代码编辑器。

这里，明哥要教你一个更加简单的方法，使用这个方法呢，你需要先安装一个库 ： decorator，使用 pip 可以很轻易地去安装它

$ python3 -m pip install decorator

从库的名称不难看出，这是一个专门用来解决装饰器问题的第三方库。

有了它之后，你会惊奇的发现，以后自己定义的装饰器，就再也不需要写嵌套的函数了

from decorator import decorator

@decorator
def deco(func, *args, **kw):
    print("Ready to run task")
    func(*args, **kw)
    print("Successful to run task")

@deco
def myfunc():
    print("Running the task")

myfunc()

deco 作为装饰函数，第一个参数是固定的，都是指被装饰函数，而后面的参数都固定使用 可变参数 *args 和 **kw 的写法，代码被装饰函数的原参数。

这种写法，不得不说，更加符合直觉，代码的逻辑也更容易理解。

带参数的装饰器

装饰器根据有没有携带参数，可以分为两种

第一种：不带参数，最简单的示例，上面已经举例

def decorator(func):
    def wrapper(*args, **kw):
        func(*args, **kw)
    return wrapper

第二种：带参数，这就相对复杂了，理解起来了也不是那么容易。

def decorator(arg1, arg2):
    def wrapper(func):
        def deco(*args, **kwargs)
            func(*args, **kwargs)
        return deco
    return wrapper

那么对于需要带参数的装饰器，decorator 是否也一样能很好的支持呢？

下面是一个官方的示例

from decorator import decorator

@decorator
def warn_slow(func, timelimit=60, *args, **kw):
    t0 = time.time()
    result = func(*args, **kw)
    dt = time.time() - t0
    if dt > timelimit:
        logging.warn('%s took %d seconds', func.__name__, dt)
    else:
        logging.info('%s took %d seconds', func.__name__, dt)
    return result
  
@warn_slow(timelimit=600)  # warn if it takes more than 10 minutes
def run_calculation(tempdir, outdir):
    pass

可以看到

• 装饰函数的第一个参数，还是被装饰器 func ，这个跟之前一样
• 而第二个参数 timelimit 写成了位置参数的写法，并且有默认值
• 再往后，就还是跟原来一样使用了可变参数的写法

不难推断，只要你在装饰函数中第二个参数开始，使用了非可变参数的写法，这些参数就可以做为装饰器调用时的参数。

签名问题有解决？

我们在自己写装饰器的时候，通常都会顺手加上一个叫 functools.wraps 的装饰器，我想你应该也经常见过，那他有啥用呢？

先来看一个例子

def wrapper(func):
    def inner_function():
        pass
    return inner_function

@wrapper
def wrapped():
    pass

print(wrapped.__name__)
#inner_function

为什么会这样子？不是应该返回 func 吗？

这也不难理解，因为上边执行func 和下边 decorator(func) 是等价的，所以上面 func.__name__ 是等价于下面decorator(func).__name__ 的，那当然名字是 inner_function

def wrapper(func):
    def inner_function():
        pass
    return inner_function

def wrapped():
    pass

print(wrapper(wrapped).__name__)
#inner_function

目前，我们可以看到当一个函数被装饰器装饰过后，它的签名信息会发生变化（譬如上面看到的函数名）

那如何避免这种情况的产生？

解决方案就是使用我们前面所说的 functools .wraps 装饰器。

它的作用就是将 被修饰的函数(wrapped) 的一些属性值赋值给 修饰器函数(wrapper) ，最终让属性的显示更符合我们的直觉。

from functools import wraps

def wrapper(func):
    @wraps(func)
    def inner_function():
        pass
    return inner_function

@wrapper
def wrapped():
    pass

print(wrapped.__name__)
# wrapped

那么问题就来了，我们使用了 decorator 之后，是否还会存在这种签名的问题呢？

写个例子来验证一下就知道啦

from decorator import decorator

@decorator
def deco(func, *args, **kw):
    print("Ready to run task")
    func(*args, **kw)
    print("Successful to run task")

@deco
def myfunc():
    print("Running the task")

print(myfunc.__name__)

输出的结果是 myfunc，说明 decorator 已经默认帮我们处理了一切可预见的问题。

总结一下

decorator 是一个提高装饰器编码效率的第三方库，它适用于对装饰器原理感到困惑的新手，可以让你很轻易的写出更符合人类直觉的代码。对于带参数装饰器的定义，是非常复杂的，它需要要写多层的嵌套函数，并且需要你熟悉各个参数的传递路径，才能保证你写出来的装饰器可以正常使用。这时候，只要用上 decorator 这个库，你就可以很轻松的写出一个带参数的装饰器。同时你也不用担心他会出现签名问题，这些它都为你妥善的处理好了。

这么棒的一个库，推荐你使用起来。

这个库可以帮你做什么呢 ？

其实很简单，就是可以帮你更方便地写python装饰器代码，更重要的是，它让 Python 中被装饰器装饰后的方法长得更像装饰前的方法。

本篇文章不会过多的向你介绍装饰器的基本知识，我会默认你知道什么是装饰器，并且懂得如何写一个简单的装饰器。

不了解装饰器的可以先去阅读我之前写的文章，非常全且详细的介绍了装饰器的各种实现方法。

常规的装饰器

下面这是一个最简单的装饰器示例，在运行 myfunc 函数的前后都会打印一条日志。

def deco(func):
    def wrapper(*args, **kw):
        print("Ready to run task")
        func(*args, **kw)
        print("Successful to run task")
    return wrapper

@deco
def myfunc():
    print("Running the task")

myfunc()

装饰器使用起来，似乎有些高端和魔幻，对于一些重复性的功能，往往我们会封装成一个装饰器函数。

在定义一个装饰器的时候，我们都需要像上面一样机械性的写一个嵌套的函数，对装饰器原理理解不深的初学者，往往过段时间就会忘记如何定义装饰器。

有一些比较聪明的同学，会利用 PyCharm 来自动生成装饰器模板

然后要使用的时候，直接敲入 deco 就会生成一个简单的生成器代码，提高编码的准备效率

使用神库

使用 PyCharm 的 Live Template ，虽然能降低编写装饰器的难度，但却要依赖 PyCharm 这一专业的代码编辑器。

这里，明哥要教你一个更加简单的方法，使用这个方法呢，你需要先安装一个库 ： decorator，使用 pip 可以很轻易地去安装它

$ python3 -m pip install decorator

从库的名称不难看出，这是一个专门用来解决装饰器问题的第三方库。

有了它之后，你会惊奇的发现，以后自己定义的装饰器，就再也不需要写嵌套的函数了

from decorator import decorator

@decorator
def deco(func, *args, **kw):
    print("Ready to run task")
    func(*args, **kw)
    print("Successful to run task")

@deco
def myfunc():
    print("Running the task")

myfunc()

deco 作为装饰函数，第一个参数是固定的，都是指被装饰函数，而后面的参数都固定使用 可变参数 *args 和 **kw 的写法，代码被装饰函数的原参数。

这种写法，不得不说，更加符合直觉，代码的逻辑也更容易理解。

带参数的装饰器

装饰器根据有没有携带参数，可以分为两种

第一种：不带参数，最简单的示例，上面已经举例

def decorator(func):
    def wrapper(*args, **kw):
        func(*args, **kw)
    return wrapper

第二种：带参数，这就相对复杂了，理解起来了也不是那么容易。

def decorator(arg1, arg2):
    def wrapper(func):
        def deco(*args, **kwargs)
            func(*args, **kwargs)
        return deco
    return wrapper

那么对于需要带参数的装饰器，decorator 是否也一样能很好的支持呢？

下面是一个官方的示例

from decorator import decorator

@decorator
def warn_slow(func, timelimit=60, *args, **kw):
    t0 = time.time()
    result = func(*args, **kw)
    dt = time.time() - t0
    if dt > timelimit:
        logging.warn('%s took %d seconds', func.__name__, dt)
    else:
        logging.info('%s took %d seconds', func.__name__, dt)
    return result
  
@warn_slow(timelimit=600)  # warn if it takes more than 10 minutes
def run_calculation(tempdir, outdir):
    pass

可以看到

• 装饰函数的第一个参数，还是被装饰器 func ，这个跟之前一样
• 而第二个参数 timelimit 写成了位置参数的写法，并且有默认值
• 再往后，就还是跟原来一样使用了可变参数的写法

不难推断，只要你在装饰函数中第二个参数开始，使用了非可变参数的写法，这些参数就可以做为装饰器调用时的参数。

签名问题有解决？

我们在自己写装饰器的时候，通常都会顺手加上一个叫 functools.wraps 的装饰器，我想你应该也经常见过，那他有啥用呢？

先来看一个例子

def wrapper(func):
    def inner_function():
        pass
    return inner_function

@wrapper
def wrapped():
    pass

print(wrapped.__name__)
#inner_function

为什么会这样子？不是应该返回 func 吗？

这也不难理解，因为上边执行func 和下边 decorator(func) 是等价的，所以上面 func.__name__ 是等价于下面decorator(func).__name__ 的，那当然名字是 inner_function

def wrapper(func):
    def inner_function():
        pass
    return inner_function

def wrapped():
    pass

print(wrapper(wrapped).__name__)
#inner_function

目前，我们可以看到当一个函数被装饰器装饰过后，它的签名信息会发生变化（譬如上面看到的函数名）

那如何避免这种情况的产生？

解决方案就是使用我们前面所说的 functools .wraps 装饰器。

它的作用就是将 被修饰的函数(wrapped) 的一些属性值赋值给 修饰器函数(wrapper) ，最终让属性的显示更符合我们的直觉。

from functools import wraps

def wrapper(func):
    @wraps(func)
    def inner_function():
        pass
    return inner_function

@wrapper
def wrapped():
    pass

print(wrapped.__name__)
# wrapped

那么问题就来了，我们使用了 decorator 之后，是否还会存在这种签名的问题呢？

写个例子来验证一下就知道啦

from decorator import decorator

@decorator
def deco(func, *args, **kw):
    print("Ready to run task")
    func(*args, **kw)
    print("Successful to run task")

@deco
def myfunc():
    print("Running the task")

print(myfunc.__name__)

输出的结果是 myfunc，说明 decorator 已经默认帮我们处理了一切可预见的问题。

总结一下

decorator 是一个提高装饰器编码效率的第三方库，它适用于对装饰器原理感到困惑的新手，可以让你很轻易的写出更符合人类直觉的代码。对于带参数装饰器的定义，是非常复杂的，它需要要写多层的嵌套函数，并且需要你熟悉各个参数的传递路径，才能保证你写出来的装饰器可以正常使用。这时候，只要用上 decorator 这个库，你就可以很轻松的写出一个带参数的装饰器。同时你也不用担心他会出现签名问题，这些它都为你妥善的处理好了。

这么棒的一个库，推荐你使用起来。

使用 from module import * 默认情况下会导入 module 里的所有变量，若你只想从模块中导入其中几个变量，可以在 module 中使用 __all__ 来控制想要被其他模块导入的变量。

# profile.py
name='wangbm'
age=27
gender='male'

__all__=['name']

打开 python console 验证一下

>>> from profile import *
>>> print(name)
wangbm
>>> print(age)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'age' is not defined
>>> print(gender)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'gender' is not defined

__all__ 仅对于使用from module import * 这种情况适用。

它经常在一个包的 __init__.py 中出现。

2. 命名空间包的神奇之处

命名空间包，一个陌生的名字。

与我们熟悉的常规包不同的是，它没有 __init__.py 文件。

更为特殊的是，它可以跨空间地将两个不相邻的子包，合并成一个虚拟机的包，我们将其称之为 命名空间包。

例如，一个项目的部分代码布局如下

foo-package/
    spam/
        blah.py

bar-package/
    spam/
        grok.py

在这2个目录里，都有着共同的命名空间spam。在任何一个目录里都没有__init__.py文件。

让我们看看，如果将foo-package和bar-package都加到python模块路径并尝试导入会发生什么？

>>> import sys
>>> sys.path.extend(['foo-package', 'bar-package'])
>>> import spam.blah
>>> import spam.grok
>>>

当一个包为命名空间包时，他就不再和常规包一样具有 __file_ 属性，取而代之的是 __path__

>>> import sys
>>> sys.path.extend(['foo-package', 'bar-package'])
>>> import spam.blah
>>> import spam.grok
>>> spam.__path__
_NamespacePath(['foo-package/spam', 'bar-package/spam'])
>>> spam.__file__
Traceback (most recent call last):
    File "<stdin>", line 1, in <module>
AttributeError: 'module' object has no attribute '__file__'

3. 包重载就是一个坑

第一种方法

>>> import spam
>>> import imp
>>> imp.reload(spam)
<module 'spam' from './spam.py'>
>>>

由于这种重载方法，只对 import module 有效，而使用 from module import arg 导入的 arg 并不会刷新。

因此，在生产环境中可能需要避免重新加载模块。而在调试模式中，它会提供一定的便利，但你要知道这个重载的弊端，以免掉入坑里。

使用 from module import * 默认情况下会导入 module 里的所有变量，若你只想从模块中导入其中几个变量，可以在 module 中使用 __all__ 来控制想要被其他模块导入的变量。

# profile.py
name='wangbm'
age=27
gender='male'

__all__=['name']

打开 python console 验证一下

>>> from profile import *
>>> print(name)
wangbm
>>> print(age)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'age' is not defined
>>> print(gender)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'gender' is not defined

__all__ 仅对于使用from module import * 这种情况适用。

它经常在一个包的 __init__.py 中出现。

2. 命名空间包的神奇之处

命名空间包，一个陌生的名字。

与我们熟悉的常规包不同的是，它没有 __init__.py 文件。

更为特殊的是，它可以跨空间地将两个不相邻的子包，合并成一个虚拟机的包，我们将其称之为 命名空间包。

例如，一个项目的部分代码布局如下

foo-package/
    spam/
        blah.py

bar-package/
    spam/
        grok.py

在这2个目录里，都有着共同的命名空间spam。在任何一个目录里都没有__init__.py文件。

让我们看看，如果将foo-package和bar-package都加到python模块路径并尝试导入会发生什么？

>>> import sys
>>> sys.path.extend(['foo-package', 'bar-package'])
>>> import spam.blah
>>> import spam.grok
>>>

当一个包为命名空间包时，他就不再和常规包一样具有 __file_ 属性，取而代之的是 __path__

>>> import sys
>>> sys.path.extend(['foo-package', 'bar-package'])
>>> import spam.blah
>>> import spam.grok
>>> spam.__path__
_NamespacePath(['foo-package/spam', 'bar-package/spam'])
>>> spam.__file__
Traceback (most recent call last):
    File "<stdin>", line 1, in <module>
AttributeError: 'module' object has no attribute '__file__'

3. 包重载就是一个坑

第一种方法

>>> import spam
>>> import imp
>>> imp.reload(spam)
<module 'spam' from './spam.py'>
>>>

由于这种重载方法，只对 import module 有效，而使用 from module import arg 导入的 arg 并不会刷新。

因此，在生产环境中可能需要避免重新加载模块。而在调试模式中，它会提供一定的便利，但你要知道这个重载的弊端，以免掉入坑里。

使用 from module import * 默认情况下会导入 module 里的所有变量，若你只想从模块中导入其中几个变量，可以在 module 中使用 __all__ 来控制想要被其他模块导入的变量。

# profile.py
name='wangbm'
age=27
gender='male'

__all__=['name']

打开 python console 验证一下

>>> from profile import *
>>> print(name)
wangbm
>>> print(age)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'age' is not defined
>>> print(gender)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'gender' is not defined

__all__ 仅对于使用from module import * 这种情况适用。

它经常在一个包的 __init__.py 中出现。

2. 命名空间包的神奇之处

命名空间包，一个陌生的名字。

与我们熟悉的常规包不同的是，它没有 __init__.py 文件。

更为特殊的是，它可以跨空间地将两个不相邻的子包，合并成一个虚拟机的包，我们将其称之为 命名空间包。

例如，一个项目的部分代码布局如下

foo-package/
    spam/
        blah.py

bar-package/
    spam/
        grok.py

在这2个目录里，都有着共同的命名空间spam。在任何一个目录里都没有__init__.py文件。

让我们看看，如果将foo-package和bar-package都加到python模块路径并尝试导入会发生什么？

>>> import sys
>>> sys.path.extend(['foo-package', 'bar-package'])
>>> import spam.blah
>>> import spam.grok
>>>

当一个包为命名空间包时，他就不再和常规包一样具有 __file_ 属性，取而代之的是 __path__

>>> import sys
>>> sys.path.extend(['foo-package', 'bar-package'])
>>> import spam.blah
>>> import spam.grok
>>> spam.__path__
_NamespacePath(['foo-package/spam', 'bar-package/spam'])
>>> spam.__file__
Traceback (most recent call last):
    File "<stdin>", line 1, in <module>
AttributeError: 'module' object has no attribute '__file__'

3. 包重载就是一个坑

第一种方法

>>> import spam
>>> import imp
>>> imp.reload(spam)
<module 'spam' from './spam.py'>
>>>

由于这种重载方法，只对 import module 有效，而使用 from module import arg 导入的 arg 并不会刷新。

因此，在生产环境中可能需要避免重新加载模块。而在调试模式中，它会提供一定的便利，但你要知道这个重载的弊端，以免掉入坑里。

当你希望在整个系统中，某个类只能出现一个实例时，就需要学会使用单例模式。

比较常见的场景是：某个项目的配置信息存放在一个配置文件中，通过一个 Config​ 的类来读取配置文件的信息。如果在程序运行期间，有很多地方都需要使用配置文件的内容，也就是说，很多地方都需要创建 Config​ 对象的实例，这就导致系统中存在多个 Config​ 的实例对象，而这样会严重浪费内存资源，尤其是在配置文件内容很多的情况下。事实上，类似 Config​ 这样的类，我们希望在程序运行期间只存在一个实例对象。

在 Python 中，可以用多种方法实现单例模式，常见的有：

• 通过使用模块
• 通过装饰器
• 通过__new__方法
• 通过元类

不同的方法，有不同的坑，对 Python 机制认识不够的同学，很容易踩到坑，本文用实例来详细说明一下这几种方法的区别，以及那些不容易被察觉的坑点，给出最佳的选择方案。

下面就详细说明以下这几种实现方法：

1. 通过使用模块

在Python中，Python 的模块就是天然的单例模式。

因为模块在第一次导入时，会生成 .pyc​ 文件，当第二次导入时，就会直接加载 .pyc​ 文件，而不会再次执行模块代码。因此，我们只需把相关的函数和数据定义在一个模块中，就可以获得一个单例对象了。

看如下示例：

# 例如在config.py文件中定义Config类和实例
class Config:
    LOG_LEVEL = 'INFO'
    ...

config = Config()


# 然后在其他文件中，通过import导入此实例
from config import config

print(config.LOG_LEVEL)
# 输出结果：INFO

如上所示，通过在文件中先生成一个类实例，然后在别的文件中直接导入这个类实例，就实现了单例模式。

2. 通过装饰器

另外一种典型的用法是使用类装饰器，由于逻辑比较易懂，被广泛被开发人员使用。

如下是一个例子，在每次对 Config 实例化的时候，都会进入 Singleton 类装饰器，该装饰器维护一个 dict，key 为 cls，value 为 instance，每次实例化都检查该 cls 是否已经在 dict 中存在，若存在则直接将之前实例化的对象返回，如此来保证单例。

from functools import wraps


def Singleton(cls):
    instance = {}

    @wraps(cls)
    def wrapper(*args, **kwargs):
        if cls not in instance:
            instance[cls] = cls(*args, **kwargs)
        return instance[cls]

    return wrapper


@Singleton
class Config(object):
    pass


cfg1 = Config()
cfg2 = Config()

print(cfg1 == cfg2)

运行后，输出结果 True​

不过，这种方法虽然逻辑非常清晰易懂，但却有一个非常大的问题：经过 Singleton 装饰的后，其返回的是函数，因为无法被继承。

装饰器由于本身机制的限制，在实例单例的同时也带来了一定的 “副作用”。

仔细一想，用装饰器实现单例的思路，不就是拦截实例对象的创建，来保证类只有唯一的实例嘛！

那我们只要换种方法，来拦截实例对象的创建不就行了。

通常的方法，有两种：

• new 方法
• 元类

3. 通过__new__方法

先说一下 new 方法，它是 Python 中的魔法方法之一。

很多人可能对他不是很熟悉，不过完全没有关系，你只要知道，当你在实例化的时候，是先执行类的 new 方法，再执行类的 init 即可。

因此，我们可以在 new 上做一些事情，使得类的实例只能存在一个。

如下是一个示例，在第一次实例的时候，会在 cls 上添加一个属性 _instance​ 来保存第一个实例，后面再实例化时，就会返回第一次创建的时候，

class Config(object):
    def __new__(cls, *args, **kwargs):
        if not hasattr(cls, '_instance'):
            cls._instance = super().__new__(cls, *args, **kwargs)
        return cls._instance


cfg1 = Config()
cfg2 = Config()

print(cfg1 == cfg2)

运行后，输出结果 True​

细心的朋友，想必已经发现，如果有其他类继承了 Config 这个类，那么 _instance​ 也同样会被子类继承过去，这会导致只要 Config 及其子类只能有一个实例，只要 Config 实例过了，其子类就不能再实例化了，但这显然不是我们所期望的。

有的朋友，可能会想到用双下划线的 __instance​，这样就不会被继承了。

很遗憾的是，双下划线的属性，虽然不会被继承，但却有一个问题，就是属性名会被 Python 修改掉，变成 _Config__instance​，这样一样，我们在编写 new 时就无法使用 hasattr 来判断。

class Config(object):
    def __new__(cls, *args, **kwargs):
        if not hasattr(cls, '__instance'):
            cls.__instance = super().__new__(cls, *args, **kwargs)
        return cls.__instance


cfg1 = Config()
print(hasattr(Config, "__instance"))          # 输出：False
print(hasattr(Config, "_Config__instance"))   # 输出：True

最好的做法是：在所有的子类将 _instance​ 重置为 None，并且重写 __new__​ 方法，最重要的是不要去调用 supper.__new__()​

class Config(object):
    def __new__(cls, *args, **kwargs):
        if not hasattr(cls, '_instance'):
            cls._instance = super().__new__(cls, *args, **kwargs)
        return cls._instance


class ConfigExt(Config):
    _instance = None

    def __new__(cls, *args, **kwargs):
        if not hasattr(cls, '_instance'):
            cls._instance = object.__new__(cls, *args, **kwargs)
        return cls._instance


cfg1 = Config()
cfg2 = ConfigExt()
cfg3 = ConfigExt()

print(cfg1 == cfg2)  # False
print(cfg2 == cfg3)  # True

可以看到，通过修改 __new__​ 方法，已经可以解决装饰器不能被继承的问题，但在有可能被继承的类里，却存在安全隐患。

4. 通过 metaclass

metaclass 是什么呢？ 用一句话说明

• 类，是用来创建实例对象的「模板」。
• 而元类，是创建类的「模板」。

因此我们可以通过修改元类，来使得创建此类时，就直接是一个单例类。

学习元类的作用过程，可以用普通类来做对比学习：

• 在创建一个实例时，会走类的 new 方法
• 同样地逻辑，在创建一个普通类时，也会走元类的 new

与此同时：

• 在类里实现了 call 可以让这个类的实例，变成可调用对象
• 对普通类进行实例化时，实际是对一个元类的实例（也就是普通类）进行直接调用，因此会走元类的 call 方法

如下是一个示例，可以发现，父类和子类都可以完美实现单例，而不需要有额外的约定，也不需要团队里的人有统一的技术积累，就像平时一样，不会有任何突兀的感觉。

class Singleton(type):
    def __init__(cls, *args, **kwargs):
        cls.__instance = None
        super().__init__(*args, **kwargs)

    def __call__(cls, *args, **kwargs):
        if not cls.__instance:
            cls.__instance = super().__call__(*args, **kwargs)
        return cls.__instance


class Config(metaclass=Singleton):
    pass


class ConfigExt(Config):
    pass


cfg1 = Config()
cfg2 = Config()
cfg3 = ConfigExt()
cfg4 = ConfigExt()

print(cfg1 == cfg2)  # True
print(cfg2 == cfg3)  # False
print(cfg3 == cfg4)  # True