[译] nodemon文档

6,092 阅读9分钟

nodemon是什么?

nodemon是一个自动重启node应用的工具,当监听的文件或监听目录下的文件发生修改时,自动重启应用。

使用nodemon不需要对应用本身的代码做任何修改。nodemon可以看作node的执行容器。使用nodemon,只需要在执行代码的时候,把node换成nodemon即可。

如何安装?

可以直接git clone代码,或者使用npm安装(推荐方法):

npm install -g nodemon

nodemon会全局安装,并添加到系统路径中。

你也可以将其作为开发依赖,安装在本地:

npm install --save-dev nodemon

如果安装在本地,无法直接通过系统路径使用。可以通过npm script(例如npm start)启动,或者使用npx nodemon启动。

如何使用?

nodemon作为应用的容器,你可以传入任何你想传入应用的参数,就跟你平时传递参数一样:

nodemon [your node app]

可以使用-h(或者 —help),查看可以传递给nodemon的选项:

nodemon -h

使用nodemon非常简单。如果你的应用接收参数host和port来启动应用,可以像下面这样写:

nodemon ./server.js localhost 8080

上面命令执行时的任何输出,都会被加上前缀[nodemon],另外你应用中的任何输出,包括错误,都会如期打印出来。

如果没有提供script.js,nodemon会寻找package.json文件,如果文件存在,则使用此文件中的main属性指定的值来执行。

你同样可以通过命令行传入inspect标志:

nodemon --inspect ./server.js 80

如果你的应用中有package.json文件,你也可以省略script的主入口,nodemon会读取package.json文件中main属性指定的值。

nodemon同样也会搜索package.json中scripts.start属性。

查看FAQ或者issues

自动重启

nodemon原本只能支持重启运行中的进程,例如web服务,但是现在也支持应用退出后,也可以重新启动。如果你的应用已经退出,nodemon依然继续监听指定目录,并在发生改变时,自动重启。

手动重启

nodemon在运行中时,如果你想重启应用,不需要退出并重新启动nodemon,你可以输入rs,按下回车键,nodemon将会重启你的应用。

配置文件

支持本地和全局配置文件。配置文件一般命名为nodemon.json,可以放置在当前目录或者你的根目录。如果配置了其他名称的配置文件,可以通过*- - config *选项指定。

它的特殊之处在于,命令行参数总是覆盖配置文件参数,参数优先级如下:

  • 命令行输入参数
  • 本地配置文件
  • 全局配置文件

配置文件可以以JSON键值对的方式规定任何命令行参数,例如:

{
	"verbose": true,
	"ignore": ["*.test.js", "fixtures/*"],
	"execMap": {
		"rb": "ruby",
		"pde": "processing --sketch={{pwd}} --run"
	}
}

我一般把上面的nodemon.json作为我的全局配置,以上配置可以支持ruby文件和处理文件,执行nodemon demo.pde,nodemon可以自动执行脚本,即使开箱即用的处理脚本。

查看更多选项

package.json

如果你想集中管理项目中的包配置,nodemon支持在package.json文件中配置。在package.json文件中,配置定义在nodemonConfig属性下,配置格式和单独的配置文件相同,例如下面的package.json配置:

{
	"name": "nodemon",
	"homepage": "http://nodemon.io",
	"...": "... other standard package.json value",
	"nodemonConfig": {
		"ignore": ["test/*", "docs/*"],
		"delay": "2500"
	}
}

注意,如果通过*- - config*指定配置文件或者配置了本地的nodemon.json,则package.json中的配置全部会被忽略。

/这个部分需要更详细的文档,但是现在你可以通过nodemon - -help查看可以配置项/

把nodemon当作一个模块使用

查看用法 另开文章翻译

把nodemon作为一个child process使用

查看用法 另开文章翻译

运行非node脚本

nodemon可以用于执行和监听其他程序项目。如果不存在nodemon.json,nodemon会读取执行脚本的后缀名,并监听此后缀名,而不是.js文件:

nodemon --exec "python -v" ./app.py

现在nodemon将会在verbose模式下基于python运行app.py(注意,如果你不需要参数时,就不需要引号中的部分),并且需要以.py为扩展名的新文件或者文件修改。

默认的可执行文件

使用nodemon.json配置文件,你可以通过execMap属性,定义自己的默认执行。当你使用的语言,不是nodemon默认支持的场景中,这个属性非常好用。

为了增加nodemon对.pl扩展名(Perl)文件的支持,你可以这样配置:

{ 
	"execMap": {
		"pl": "perl"
	}
}

现在执行以下代码,nodemon就知道使用perl作为可执行环境:

nodemon script.pl

推荐使用全局配置来增加你自己的execMap选项。当然,如果你发现任何常见选项缺失,你可以修改default.js,并发送一个pull request,经过确认后,nodemon可以默认支持。

监听多个目录

nodemon默认监听当前的工作目录。如果你想自己控制监听范围,可以使用*- - watch*参数增加指定的路径:

nodemon --watch app --watch libs app/server.js

当app或者libs有修改时,都会触发重新启动。nodemon默认会遍历子目录,所以不用特意指定子目录。

不要使用通配符来传递多个目录,例如- - watch ./lib/*,这种方式不生效。你需要使用- - watch指定每一个需要监听的目录。

指定监听对象的扩展名

nodemon默认监听对象扩展名有.js/.mjs/.coffee/.litcoffee/.json。如果你使用*- - exec选项并监听app.py,nodemon会监听以.py为扩展名的文件。你也可以使用-e 或者 - - ext*来指定自己的列表,如下:

nodemon -e js,pug

现在nodemon也会监听以.js或者.pug为扩展名的文件了。

忽略文件

nodemon默认在.js文件修改时,重启应用。有时候也许,你想忽略某些文件/目录/文件名称模式(匹配文件名),来阻止nodemon过早的重启应用。

使用*- - ignore*可以忽略指定文件:

nodemon --ignore lib/ --ignore tests/

或者指定某个文件被忽略

nodemon --ignore lib/app.js

指定pattern,可以忽略匹配文件(但是要确定要用引号包含参数):

nodemon --ignore 'lib/*.js'

注意,默认忽略.git/node_modules/bower_components/.nyc_output/coverage/.saas-cache目录,你可以添加自己的忽略patterns到这个列表中。如果你确实想监听node_modules这样的文件夹,你需要重写底层默认忽略列表

应用没有重新启动

在一些网络环境中(例如一个运行nodemon的容器通过挂载的驱动读取),你需要使用legacyWatch: true,启动Chokidar轮询:

通过命令行,使用参数- - legacy-watch或者-L:

nodemon -L

这个参数是保留方法,因为它将会轮询所有它能找到的文件。

延迟重启

在某些场景中,你也许想等待一定数量的文件修改之后,才重启应用。默认预留1s事件等待新的文件修改。如果你上传一定数量的文件,将要花费数秒时间时,可能会引起你的应用频繁重启。

使用- - delay选项可以延迟指定时间之后重启:

nodemon --delay 10 server.js

延迟时间可以精确到毫秒。例如:

nodemon --delay 2.5 server.js

或者指定时间单位

nodemon --delay 2500ms server.js

delay参数指定延迟多少秒(或者毫秒)之后重启。因此nodemon将会在最后文件修改之后指定的延迟时间重启。

如果你在nodemon.json中指定延迟的时间,则单位默认为ms。下面的2种写法时等价的:

nodemon --delay 2.5 { "delay": "2500" }

优雅的重载脚本

nodemon可以发送你指定的信号到你的应用中。

nodemon --signal SIGHUP server.js

你的应用可以如下使用信号:

process.once("SIGHUP", () => {
	reloadSomeConfiguration();
})

注意,nodemon将会给进程树中的每一个进程发送信号。

如果你使用cluster,每一个worker(和master一样)都会收到信号。如果你希望阻止所有workers接收SIGHUP,一种常见的方式时在master中捕获SIGHUP,向所有workers传播SIGTERM,这样就可以保证所有的workers忽略SIGHUP。

if (cluster.isMaster) {
	process.on("SIGHUP", () => {
		for(const worker of Object.values(cluster.workers)) {
			workder.process.kill("SIGTERM")
		}
	})
} else {
	process.on("SIGHUP", () => {})
}

控制脚本的退出

nodemon在监听到文件更新时,会像你的应用发送一个kill信号。如果你需要在你的脚本退出时做一些清除工作,你可以捕获这个kill信号,并且自己处理。

下面的例子中,监听一次SIGUSR2信号(nodemon用于重启的信号),运行清除进程,然后kill它自己,以便nodemon继续控制。

process.once('SIGUSR2', () => {
	gracefulShutdown(() => {
		process.kill(process.pid, 'SIGUSR2');
	})
})

注意,在退出工作完成时,只需要调用一次process.kill方法。使用案例

nodemon状态修改时触发事件

如果你想在nodemon重启发出通知,或者当某个事件发生时,触发某个行为,你可以对nodemon提出pr或者在nodemon.json文件中增加事件actions。

例如,在Mac系统中,nodemon重启时,触发一个通知,可以如下定义:

{
	"events": {
		"restart": "osascript - e 'display notification \"app restarted\"' with title \"nodemon\"'"
	}
}

详细状态列表。你可以绑定所有状态和信息。

输出信息到其他地方

nodemon({
	script: ...,
	stdout: false // 重要,设置为false,代表不要输出到console中
}).on('readable', () => {
	this.stdout.pipe(fs.createWriteStream('output.txt'));
	this.stderr.pipe(fs.createWriteStream('err.txt'));
})

与glup一起工作

使用gulp-nodemon插件,可以将nodemon整合到你的gulp工作流中。

与Grunt一起工作

使用gunt-nodemon插件,可以将nodemon整合到你的grunt工作流中。

nodemon如何发音?

nodemon应该如何发音?node-mon, no-demon, 或者node-e-mon?

额~之前被多次问到这个问题。我很高心你们有这样的疑惑。还有人打赌到底哪一种念法才是正确的。

其实答案很简单,但是可能会让你失望。我不会告诉你我是如何念它的。它的念法决定于你自己。所有答案都是正确的~

设计原则

  • 尽量少的flags
  • 全平台通用
  • 尽量少的特性
  • 基于nodemon独立(我觉得意思就是,即使没有nodemon,也可以独立运行)
  • 提供所有CLI函数作为API
  • 测试覆盖率100%

Nodemon是不完美的,CLI参数过于松散,这让我很不高兴,但是也许有一天会减少一两个。

FAQ

查看FAQ,请提出你觉得有帮助的问题。