gitbook入门教程之解决windows热加载失败问题雪之梦技术驿站

gitbook在Windows系统无法热加载,总是报错!

gitbook是一款文档编写利器,可以方便地markdown输出成美观优雅的html,gitbookserve启动服务器后,原来相貌平平的markdown丑小鸭摇身一变就成了倾国倾城的html绝色佳人.

如果源文件发生更改,Windows却无法按照预期那样重启服务器,直接抛出一个异常,立即终止了markdown的化妆.

RestartafterchangeinfileREADME.mdStoppingserverevents.js:183thrower;//Unhandled'error'event^Error:EPERM:operationnotpermitted,lstat'F:\workspace\private-cloud-backup\gitbook-test\_book'对镜贴花黄现在看一下markdown灰姑娘变身html小姐姐的神奇过程吧!

另外一个是35729端口,用于监听本地文件变化,重启服务器进而实现热加载功能.

不幸的是,Windows热加载可能会有问题,也就是说如果启动服务器后,本地文件发生改变,此时会触发热加载功能而报错Error:EPERM:operationnotpermitted,这样一来浏览器又无法访问了.

刚刚变身的markdown瞬间又被打回原形,无法欣赏化妆后的容颜了,这样的体验相当不好!

边化妆边照镜子才是做到心中有谱,随时调整,如果不照镜子而直接化妆,那不是一般人能做到的.

gitbook启动本地服务器给我们提供了镜子,但热加载失败又把镜子摔碎了,还怎么愉快的化妆

RestartafterchangeinfileREADME.mdStoppingserverdebug:readmefoundatREADME.mddebug:summaryfilefoundatSUMMARY.mddebug:cleanupfolder"G:\sublime\gitbook-test\_book"events.js:174thrower;//Unhandled'error'event^Error:EPERM:operationnotpermitted,lstat'G:\sublime\gitbook-test\_book'Emitted'error'eventat:atFSWatcher._handleError(C:\Users\snowdreams1006\.gitbook\versions\3.2.3\node_modules\chokidar\index.js:236:10)atReaddirpReadable.emit(events.js:189:13)atImmediate.(C:\Users\snowdreams1006\.gitbook\versions\3.2.3\node_modules\chokidar\node_modules\readdirp\stream-api.js:82:32)atrunCallback(timers.js:705:18)attryOnImmediate(timers.js:676:5)atprocessImmediate(timers.js:658:5)寻医问诊修破镜现在问题已经复现,接下来就要开始寻医问诊,试图让破镜重圆,好让markdown灰姑娘变成人见人爱的html小姐姐.

根据报错信息描述,定位到删除_book目录再次创建该目录时,提示EPERM:operationnotpermitted,即无权操作.

既然说是操作权限的问题,那我们看一下_book目录现在是怎样状态吧!

$lsgitbook-errorforwindows-preview.pngREADME.mdSUMMARY.md当前项目已经没有_book目录,证明发生报错时确实已经删除了_book目录,但是某种原因无权再次创建该文件夹而重启失败.

然而,这只是表现现象,老师告诉我们,要透过现象看本质,即使现在没有_book文件再次启动服务器还是会启动成功并创建_book文件的,所以真想只有一个!

那就是,gitbook控制台在说谎!

虽然排除了gitbook无权创建_book目录的嫌疑,那又怎么解释重启服务器却没能创建_book目录这件事呢

debug:cleanupfolder"G:\sublime\gitbook-test\_book"events.js:174thrower;//Unhandled'error'event^Error:EPERM:operationnotpermitted,lstat'G:\sublime\gitbook-test\_book'Emitted'error'eventat:atFSWatcher._handleError(C:\Users\snowdreams1006\.gitbook\versions\3.2.3\node_modules\chokidar\index.js:236:10)atReaddirpReadable.emit(events.js:189:13)atImmediate.(C:\Users\snowdreams1006\.gitbook\versions\3.2.3\node_modules\chokidar\node_modules\readdirp\stream-api.js:82:32)atrunCallback(timers.js:705:18)attryOnImmediate(timers.js:676:5)atprocessImmediate(timers.js:658:5)先看一下FSWatcher._handleError异常信息:sed-n"223,239p"~/.gitbook/versions/3.2.3/node_modules/chokidar/index.js.

分析发现:FSWatcher._handleError是私有方法,作用是处理异常信息,和这起事故关联不大.

Administrator@snowdreams1006MINGW64/f/workspace/private-cloud-backup/gitbook-test(master)$sed-n"223,239p"~/.gitbook/versions/3.2.3/node_modules/chokidar/index.js//Privatemethod:Commonhandlerforerrors////*error-object,Errorinstance////Returnstheerrorifdefined,otherwisethevalueofthe//FSWatcherinstance's`closed`flagFSWatcher.prototype._handleError=function(error){varcode=error&&error.code;varipe=this.options.ignorePermissionErrors;if(error&&code!=='ENOENT'&&code!=='ENOTDIR'&&(!ipe||(code!=='EPERM'&&code!=='EACCES')))this.emit('error',error);returnerror||this.closed;};我们接着往下找,再看一下ReaddirpReadable.emit(events.js:189:13),这里没有给出文件的具体路径,所以暂时无法定位.

那我们再看下一个Immediate.:sed-n"78,96p"~/.gitbook/versions/3.2.3/node_modules/chokidar/node_modules/readdirp/stream-api.js

Administrator@snowdreams1006MINGW64/f/workspace/private-cloud-backup/gitbook-test(master)$sed-n"78,96p"~/.gitbook/versions/3.2.3/node_modules/chokidar/node_modules/readdirp/stream-api.jsproto._handleFatalError=function(err){varself=this;setImmediate(function(){if(self._paused)returnself._errors.push(err);if(!self._destroyed)self.emit('error',err);});}functioncreateStreamAPI(){varstream=newReaddirpReadable();return{stream:stream,processEntry:stream._processEntry.bind(stream),done:stream._done.bind(stream),handleError:stream._handleError.bind(stream),handleFatalError:stream._handleFatalError.bind(stream)};}遗憾的是,仍然没有找到具体问题,那就继续看一下一条线索.

timers.js:705:18和events.js:189:13都没有显示具体的文件位置,如果也在chokidar模块的话就好了.

经过肉眼验证,发现events.js根本就没有174行文件,所以这两个文件大都不是目标文件.

既然命令行中无法找到目标文件,那就请专业的搜索工具全系统查找这两个文件吧,这里使用的是Everything搜索工具.

然并卵,依然没有找到目标文件.

毕竟不是柯南,没有发现真相

gitbook可是开源产品,出现问题的应该不止我一个,所以去github看看有没有遇到和我一样的问题.

虽然找到了志同道合的小伙伴,但是并没有提供解决方案,连官方都放弃了,那我还有什么可留恋的

最害怕的不是bug,而是发现了bug却无法定位,虽然控制台有报错信息但是没有找到真正的文件!

首先确认下当前系统版本,然后采取版本切换方式测试其他版本是否存在该问题.

$gitbook--versionCLIversion:2.3.2GitBookversion:3.2.3gitbookls是列出当前已安装的版本,而gitbookls-remote则是列出远程服务器版本.

看到4.0.0-alpha.6心里有些忐忑,根据版本管理约定,版本号一般有三部分组成,第一部分代表不兼容的重大升级,第二部分代表主干兼容的功能升级,第三部分是小版本修复.

由3.2.3直接跨度到4.0.0-alpha.6意味着gitbook发生了重大重构!

算了,先下载试试看!

gitbookfetch下载和gitbookupdate升级,两种方式都可以体验最新版本,这里选择下载方式方便进行不同版本的切换.

#下载`4.0.0-alpha.6`版本$gitbookfetch4.0.0-alpha.6InstallingGitBook4.0.0-alpha.6gitbook@4.0.0-alpha.6C:\Users\SNOWDR~1\AppData\Local\Temp\tmp-8912hSrxNvTCrFEH\node_modules\gitbook├──escape-html@1.0.3├──escape-string-regexp@1.0.5├──destroy@1.0.4├──ignore@3.1.2└──ied@2.3.6(lodash.memoize@4.1.2,lodash.frompairs@4.0.1,force-symlink@0.0.2,semver@5.7.0,minimist@1.2.0,node-uuid@1.4.8,npm-package-arg@4.2.1,source-map-support@0.4.18,ora@0.2.3,easy-table@1.1.1,rimraf@2.6.3,tar-fs@1.16.3,gunzip-maybe@1.4.1,init-package-json@1.10.3,rxjs@5.0.0-rc.1,needle@1.0.0,node-pre-gyp@0.6.39,node-gyp@3.8.0)GitBook4.0.0-alpha.6hasbeeninstalled先看一下本地安装gitbook版本,确保待会运行时使用最新的4.0.0-alpha.6版本.

#列出本地已安装版本$gitbooklsGitBookVersionsInstalled:*4.0.0-alpha.63.2.3Run"gitbookupdate"toupdatetothelatestversion.#列出当前正在使用版本$gitbookcurrentGitBookversionis3.2.3gitbookserve--gitbook=4.0.0-alpha.6--log=debug运行4.0.0-alpha.6版本并打印debug级别日志.

意外的是,竟然没有连启动都没启动成功,提示无法打开~\.gitbook\versions\4.0.0-alpha.6\node_modules\gitbook-plugin-livereload\_assets\plugin.js文件.

回想到版本号规范,可能v3到v4更改比较大,版本不兼容吧,重新初始化项目试试看!

当前系统版本是3.2.3,最新测试版本是4.0.0-alpha.6,然而最近一次提交的版本却是2.6.9

为什么gitbook-ci管理的gitbook版本号会突然跳水,会不会有什么猫腻,难不成修复了什么bug

$gitbookls-remoteAvailableGitBookVersions:4.0.0-alpha.6,4.0.0-alpha.5,4.0.0-alpha.4,4.0.0-alpha.3,4.0.0-alpha.2,4.0.0-alpha.1,3.2.3,3.2.2,3.2.1,3.2.0,3.2.0-pre.1,3.2.0-pre.0,3.1.1,3.1.0,3.0.3,3.0.2,3.0.1,3.0.0,3.0.0-pre.15,3.0.0-pre.14,3.0.0-pre.13,3.0.0-pre.12,3.0.0-pre.11,3.0.0-pre.10,3.0.0-pre.9,3.0.0-pre.8,3.0.0-pre.7,3.0.0-pre.6,3.0.0-pre.5,3.0.0-pre.4,3.0.0-pre.3,3.0.0-pre.2,3.0.0-pre.1,2.6.9,2.6.8,2.6.7,2.6.6,2.6.5,2.6.4,2.6.3,2.6.2,2.6.1,2.6.0,2.5.2,2.5.1,2.5.0,2.5.0-beta.7,2.5.0-beta.6,2.5.0-beta.5,2.5.0-beta.4,2.5.0-beta.3,2.5.0-beta.2,2.5.0-beta.1,2.4.3,2.4.2,2.4.1,2.4.0,2.3.3,2.3.2,2.3.1,2.3.0,2.2.0,2.1.0,2.0.4,2.0.3,2.0.2,2.0.1,2.0.0,2.0.0-beta.5,2.0.0-beta.4,2.0.0-beta.3,2.0.0-beta.2,2.0.0-beta.1,2.0.0-alpha.9,2.0.0-alpha.8,2.0.0-alpha.7,2.0.0-alpha.6,2.0.0-alpha.5,2.0.0-alpha.4,2.0.0-alpha.3,2.0.0-alpha.2,2.0.0-alpha.1Tags:latest:2.6.9pre:4.0.0-alpha.6带着这些疑问,不妨下载2.6.9版本试试,看一下能否热加载

gitbookserve--log=debug--gitbook=2.6.9指定gitbook版本,依旧失败!

$gitbookserve--log=debug--gitbook=2.6.9Errorloadingversionlatest:Error:Cannotfindmodule'q'atFunction.Module._resolveFilename(internal/modules/cjs/loader.js:582:15)atFunction.Module._load(internal/modules/cjs/loader.js:508:25)atModule.require(internal/modules/cjs/loader.js:637:17)atrequire(internal/modules/cjs/helpers.js:22:18)atObject.(C:\Users\myHome\.gitbook\versions\2.6.9\lib\index.js:3:9)atModule._compile(internal/modules/cjs/loader.js:701:30)atObject.Module._extensions..js(internal/modules/cjs/loader.js:712:10)atModule.load(internal/modules/cjs/loader.js:600:32)attryModuleLoad(internal/modules/cjs/loader.js:539:12)atFunction.Module._load(internal/modules/cjs/loader.js:531:3)TypeError:Cannotreadproperty'commands'ofnull重回现场现在把目光再次聚焦到最初的案发现场,这一次只能背水一战了,自己动手要么丰衣足食要么饿死冻死!

Stoppingserverdebug:readmefoundatREADME.mddebug:summaryfilefoundatSUMMARY.mddebug:cleanupfolder"G:\sublime\private-cloud-backup\gitbook-test\_book"events.js:174thrower;//Unhandled'error'event^Error:EPERM:operationnotpermitted,lstat'G:\sublime\private-cloud-backup\gitbook-test\_book'Emitted'error'eventat:atFSWatcher._handleError(C:\Users\myHome\.gitbook\versions\3.2.3\node_modules\chokidar\index.js:236:10)atReaddirpReadable.emit(events.js:189:13)atImmediate.(C:\Users\myHome\.gitbook\versions\3.2.3\node_modules\chokidar\node_modules\readdirp\stream-api.js:82:32)atrunCallback(timers.js:705:18)attryOnImmediate(timers.js:676:5)atprocessImmediate(timers.js:658:5)关于上述错误描述中,在真相只有一个章节中已经探讨过,当时得出的结论是gitbook是删除_book文件夹再新建_book文件夹时发生了意外.

如果这个行为不是由gitbook发生而是由我们手动干预的话,也就是说,当成功启动本地服务器后并在即将发生热加载之前,此时人为删除_book文件夹,会发生什么

我的猜想是:

因为gitbook的热加载机制是监听本地文件目录系统发生改变,进而停止服务器再重新启动服务器.

当我们手动删除了_book文件夹,对于gitbook来说,再触发重启服务器的那一刻来说,突然发现没有_book文件夹,此时就不会删除也不会新建时发生异常,相当于直接新建_book文件夹,变相把热加载弄成了初始启动模式!

希望苍天不负我,如若不行,只能看源码逻辑找bug了!

你猜猜会怎么样itworks!

到此为止,总算找到一个解决方案,那就是启动服务后立即删除_book目录.

windows系统上启动gitbook服务后,如果本地文件发生更改,热加会失败.

如果启动服务器后立即删除_book目录,那么之后再怎么修改本地文件都能顺利重启.

目前还没有找到问题的根源,下一次将深入源码继续探讨到底是哪里出问题导致Windows系统无法重启.

虽然及时删除_book目录并不算是很好的解决方案,但至少markdown灰姑娘又能化妆成html小姐姐了呢!