📖 本教程更新於 2020 年 09 月 28 日,教程的內容針對最新穩定版而更新(如果你是舊版,教程會有些出入,請留意)

🦋 Butterfly 已經更新到 3.2.0

如果有安裝這兩個插件的,請卸載掉,會導致主題報錯。
hexo-injecthexo-neat


以下是一些網友在安裝的過程中出現的問題。在提問題之前,先看有沒有解決方法。

運行後網頁顯示代碼

頁面只顯示 extends includes/layout.pug block content #recent-posts.recent-posts include includes/recent-posts.pug include includes/pagination.pug #aside_content.aside_content include includes/aside.pug

請下載安裝:npm install hexo-renderer-pug hexo-renderer-stylus --save or `yarn add hexo-renderer-pug hexo-renderer-stylus

配置友情鏈接報錯

配置友情鏈接頁面時出現報錯

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
ERROR D:\Desktop\orxing-blog\themes\Butterfly\layout\flink.pug:2
1| .flink
> 2| each i in site.data.link
3| p.comment-word= i.class_name
4| .post-cards
5| ul.md-links

Cannot read property 'length' of undefined
TypeError: D:\Desktop\orxing-blog\themes\Butterfly\layout\flink.pug:2
1| .flink
> 2| each i in site.data.link
3| p.comment-word= i.class_name
4| .post-cards
5| ul.md-links

Cannot read property 'length' of undefined
at eval (eval at wrap (D:\Desktop\orxing-blog\node_modules\pug-runtime\wrap.js:6:10), <anonymous>:1890:32)
at eval (eval at wrap (D:\Desktop\orxing-blog\node_modules\pug-runtime\wrap.js:6:10), <anonymous>:2017:4)
at template (eval at wrap (D:\Desktop\orxing-blog\node_modules\pug-runtime\wrap.js:6:10), <anonymous>:10152:72)
at Theme._View.View._compiled (D:\Desktop\orxing-blog\node_modules\hexo\lib\theme\view.js:123:48)
at Theme._View.View.View.render (D:\Desktop\orxing-blog\node_modules\hexo\lib\theme\view.js:29:15)
at D:\Desktop\orxing-blog\node_modules\hexo\lib\hexo\index.js:349:21
at tryCatcher (D:\Desktop\orxing-blog\node_modules\bluebird\js\release\util.js:16:23)
at D:\Desktop\orxing-blog\node_modules\bluebird\js\release\method.js:15:34
at RouteStream._read (D:\Desktop\orxing-blog\node_modules\hexo\lib\hexo\router.js:123:3)
at RouteStream.Readable.read (_stream_readable.js:457:10)
at resume_ (_stream_readable.js:936:12)
at processTicksAndRejections (internal/process/task_queues.js:84:9)

請檢查 link.yml文檔內代碼的空格

升級最新版後運行報錯

升級最新版本hexo g後報錯

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
INFO  Deleted database.
INFO Start processing
FATAL Something's wrong. Maybe you can find the solution here: https://hexo.io/docs/troubleshooting.html
TypeError: Cannot read property 'enable' of undefined
at Hexo.<anonymous> (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/themes/Butterfly/scripts/post-lazyload.js:5:23)
at Hexo.tryCatcher (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/util.js:16:23)
at Hexo.<anonymous> (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/method.js:15:34)
at /Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/hexo/lib/extend/filter.js:60:50
at tryCatcher (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/util.js:16:23)
at Object.gotValue (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/reduce.js:155:18)
at Object.gotAccum (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/reduce.js:144:25)
at Object.tryCatcher (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/util.js:16:23)
at Promise._settlePromiseFromHandler (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/promise.js:517:31)
at Promise._settlePromise (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/promise.js:574:18)
at Promise._settlePromiseCtx (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/promise.js:611:10)
at _drainQueueStep (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/async.js:142:12)
at _drainQueue (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/async.js:131:9)
at Async._drainQueues (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/async.js:147:5)
at Immediate.Async.drainQueues [as _onImmediate] (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/async.js:17:14)
at processImmediate (internal/timers.js:439:21)

請參照最新版的_config.yml, 比對後,把缺的配置複製到主題配置文件中去

wordcount is not a function / totalcount is not a function

報錯wordcount is not a function

請檢查是否安裝了wordcount插件 npm i --save hexo-wordcount

升級2.0.0後運行報錯

舊版本升級到2.0.0後報錯

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
INFO Start processing
FATAL Something’s wrong. Maybe you can find the solution here: https://hexo.io/docs/troubleshooting.html
Template render error: (unknown path)
unexpected end of file
at Object.prettifyError (F:\hexo\nodemodules\nunjucks\src\lib.js:36:11)
at Template.render (F:\hexo\node_modules\nunjucks\src\environment.js:542:21)
at Environment.renderString (F:\hexo\node_modules\nunjucks\src\environment.js:380:17)
at Promise.fromCallback.cb (F:\hexo\node_modules\hexo\lib\extend\tag.js:123:48)
at tryCatcher (F:\hexo\node_modules\bluebird\js\release\util.js:16:23)
at Function.Promise.fromNode.Promise.fromCallback (F:\hexo\node_modules\bluebird\js\release\promise.js:185:30)
at Tag.render (F:\hexo\node_modules\hexo\lib\extend\tag.js:123:18)
at Object.onRenderEnd (F:\hexo\node_modules\hexo\lib\hexo\post.js:280:20)
at Promise.then.then.result (F:\hexo\node_modules\hexo\lib\hexo\render.js:64:19)
at tryCatcher (F:\hexo\node_modules\bluebird\js\release\util.js:16:23)
at Promise.settlePromiseFromHandler (F:\hexo\nodemodules\bluebird\js\release\promise.js:517:31)

2.0.0版本以上刪掉了gallery,而引入新的gallery。所以如果有使用舊版,需刪掉或者更改寫法。

代碼渲染與實際不同

2.1.0 以下版本會出現的問題

代碼渲染與實際不同

1
<div>aaa</div>

渲染結果:

cheerio版本錯誤,請安裝0.22.0版本

npm install cheerio@0.22.0 –save

搜索欄在底部

hexo deploy後搜索欄在頁面底部

生成前先hexo clean

本地可以正常運行,但是push上去後出錯/缺失/無效

  1. 清理瀏覽器緩存
  2. 如果1無效,請確認上傳時是否有運行 hexo clean

已在Hexo的配置文件設置了語言,為什麼導航欄仍然是英文

請在導航的配置裏,自己修改成想要的中文

1
2
3
4
首頁: / || fa fa-home
時間軸: /archives/ || fa fa-archive
標籤: /tags/ || fa fa-tags
分類: /categories/ || fa fa-folder-open

運行報錯 Cannot read property ‘bind’ of undefined/full_url_for is not function

1
TypeError: Cannot read property 'bind' of undefined

把Hexo升級到4.0以上版本

Cannot read property ‘appId’ of undefined

報錯

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
  > 1| -
2| var algolia = 'undefined';
3| var env = process.env;
4| if (theme.algolia_search.enable) {

Cannot read property 'appId' of undefined
at eval (eval at wrap (F:\github\Blog\blog\node_modules\pug-runtime\wrap.js:6:10), <anonymous>:8:49)
at template (eval at wrap (F:\github\Blog\blog\node_modules\pug-runtime\wrap.js:6:10), <anonymous>:329:53)
at _View._compiledSync (F:\github\Blog\blog\node_modules\hexo\lib\theme\view.js:132:24)
at _View.renderSync (F:\github\Blog\blog\node_modules\hexo\lib\theme\view.js:59:25)
at F:\github\Blog\blog\node_modules\hexo\lib\plugins\helper\partial.js:31:52
at Cache.apply (F:\github\Blog\blog\node_modules\hexo\node_modules\hexo-util\lib\cache.js:27:46)
at Object.fragmentCache (F:\github\Blog\blog\node_modules\hexo\lib\plugins\helper\fragment_cache.js:11:34)
at Object.partial (F:\github\Blog\blog\node_modules\hexo\lib\plugins\helper\partial.js:31:17)
at eval (eval at wrap (F:\github\Blog\blog\node_modules\pug-runtime\wrap.js:6:10), <anonymous>:149:46)
at template (eval at wrap (F:\github\Blog\blog\node_modules\pug-runtime\wrap.js:6:10), <anonymous>:5213:93)
at _View._compiled (F:\github\Blog\blog\node_modules\hexo\lib\theme\view.js:136:50)
at _View.render (F:\github\Blog\blog\node_modules\hexo\lib\theme\view.js:39:17)
at F:\github\Blog\blog\node_modules\hexo\lib\hexo\index.js:64:21
at tryCatcher (F:\github\Blog\blog\node_modules\hexo\node_modules\bluebird\js\release\util.js:16:23)
at F:\github\Blog\blog\node_modules\hexo\node_modules\bluebird\js\release\method.js:15:34
at RouteStream._read (F:\github\Blog\blog\node_modules\hexo\lib\hexo\router.js:30:5)
at RouteStream.Readable.read (_stream_readable.js:490:10)
at resume_ (_stream_readable.js:975:12)
at processTicksAndRejections (internal/process/task_queues.js:80:21) {
path: 'F:\\github\\Blog\\blog\\themes\\Butterfly\\layout\\includes\\head.pug'
}

algolia 插件安裝後還需要配置
查看插件文檔配置

⚡️ Butterfly 安裝文檔(六) 進階教程