nodemon.json 配置完全指南基于官方示例文件逐项解读 nodemon 的核心配置项【免费下载链接】nodemonMonitor for any changes in your node.js application and automatically restart the server - perfect for development项目地址: https://gitcode.com/gh_mirrors/no/nodemon导读nodemon.json是 nodemon 的配置文件用于把监听哪些文件、何时重启、用什么命令执行、注入什么环境变量等开发期行为固化下来。本文以 nodemon 仓库官方文档 doc/sample-nodemon.md 中的示例文件为骨架逐项拆解restartable、ignore、verbose、execMap、events、watch、env、ext这 8 个配置键的语义、默认值与底层实现并结合 lib/config/defaults.js、lib/config/load.js、lib/monitor/run.js 等源码说明它们如何真实生效。读完本文你将能够读懂并编写一份可投入实战的 nodemon 配置文件并掌握配置优先级与调试验证手段。一、nodemon.json 的角色配置文件从哪来、谁覆盖谁nodemon 支持在项目目录当前工作目录和用户主目录放置nodemon.json配置文件也支持通过--config file指定任意位置的替代配置文件。配置文件可以承载任何命令行参数的 JSON 形式。配置的生效优先级高到低为命令行参数——始终覆盖配置文件本地配置——当前工作目录下的nodemon.json全局配置——用户主目录下的nodemon.json。这一规则在 lib/config/load.js 的load函数中有明确的实现顺序先读取utils.home下的全局配置再读取process.cwd()下的本地配置最后用命令行解析出的 settings 通过utils.merge(settings, options)合并覆盖merge 保护已有值因此命令行参数优先级最高见 load.js 中注释。二、示例文件全貌官方示例一个刻意编排的演示性配置如下本文后续所有小节都围绕它展开{ restartable: rs, ignore: [ .git, node_modules/**/node_modules ], verbose: true, execMap: { js: node --harmony }, events: { restart: osascript -e display notification \App restarted due to:\n$FILENAME\ with title \nodemon\ }, watch: [ test/fixtures/, test/samples/ ], env: { NODE_ENV: development }, ext: js,json }三、逐项解读 8 个核心配置键1.restartable手动触发重启的命令restartable: rsnodemon 运行期间你可以在终端输入该字符串并回车强制重启当前监听的子进程而不必退出 nodemon 再重新启动。默认值正是rs见 lib/config/defaults.js 第 5 行restartable: rs。在 lib/monitor/run.js 中子进程退出后会检查config.options.restartable并重新process.stdin.resume()以便继续监听标准输入中的重启命令而bus.on(restart)监听器会调用run.kill()杀掉子进程树再由子进程的exit事件处理器触发重启。这也解释了手动重启是走杀进程 → 重新拉起的完整链路而非原地热更新。2.ignore忽略文件 / 目录规则ignore: [ .git, node_modules/**/node_modules ]官方文档特别注明示例中的ignore用的正是 nodemon 的默认忽略规则。nodemon 默认忽略.git、node_modules、bower_components、.nyc_output、coverage、.sass-cache等目录这些目录来自ignore-by-default包并统一转换为**/dir/**形式的 glob 规则即 lib/config/defaults.js 第 15 行的ignoreRoot。关键点在于你配置的ignore不会替换默认忽略项而是与之合并。在 lib/config/load.js 第 62–69 行nodemon 会先把options.ignoreRoot默认忽略与用户options.ignore拼接成同一个数组再统一交给规则引擎。也就是说即使你的配置文件里写的是node_modules/**/node_modules这种嵌套规则.git等默认目录依然会被忽略。若确实想监听node_modules之类的默认忽略目录需要显式覆盖底层 ignoreRoot 规则。从匹配实现看lib/monitor/match.js所有 watch / ignore 规则都会以绝对路径 minimatch 进行匹配dot: trueWindows 下开启nocaseignore 规则以!前缀叠加在 watch 规则之后且 ignore 规则在排序中优先级最高见match函数中的排序逻辑。3.verbose输出导致重启的详细原因verbose: true默认值为falselib/config/defaults.js 第 19 行。开启后nodemon 会输出哪条规则匹配了哪个文件、为什么触发重启等细节。在 lib/config/load.js 第 102–104 行配置加载完成后若options.verbose为真会把utils.debug置为true而匹配器lib/monitor/match.js中大量utils.log.detail(matched rule: ...)之类的调试输出正是依赖这个开关。命令行等价写法是-V/--verbose。4.execMap按扩展名映射可执行程序execMap: { js: node --harmony }execMap用于建立文件扩展名 → 执行命令的映射使得nodemon xxx.ext时无需显式--exec也能找到正确的解释器。nodemon 内置的默认映射lib/config/defaults.js 第 7–14 行包括扩展名默认执行程序pypythonrbrubytsts-node注意当环境变量NODE_OPTIONS中包含--loader或--import时默认的ts映射会被删除defaults.js 第 28–32 行以避免与 Node 的 ESM loader 机制冲突。在 lib/config/exec.js 第 135–138 行只有当用户没有显式指定exec时nodemon 才会回退到execMap[scriptExt]因此execMap是兜底而非强制。示例中的js: node --harmony属于演示性写法--harmony是早期 Node 的 harmony 特性开关在真实项目中你更可能像这样扩展非默认语言{ execMap: { pl: perl, pde: processing --sketch{{pwd}} --run } }execMap的值还支持{{filename}}与{{pwd}}变量替换exec.js 第 150–164 行其中{{pwd}}会被替换为process.cwd()。官方建议把自定义的execMap放在全局nodemon.json这样所有项目都能受益。5.events在 nodemon 状态变化时执行外部命令events: { restart: osascript -e display notification \App restarted due to:\n$FILENAME\ with title \nodemon\ }events允许把 nodemon 的生命周期事件绑定到一段 shell 命令。示例在 macOS 上通过osascript在每次重启时弹出一条系统通知通知内容中通过$FILENAME引用触发重启的文件。实现上nodemon 通过事件总线bus广播事件事件种类详见 doc/events.md包括命令类restart、config:update、quit状态类start子进程启动、crash子进程崩溃此时不触发exit、exit子进程正常退出、restart传入触发重启的文件数组消息类log、stdout、stderr、readable。在 lib/nodemon.js 第 233–244 行配置加载完成后nodemon 会遍历config.options.events的每个键用nodemon.on(key, ...)绑定事件并在触发时通过 lib/spawn.js 以子进程方式执行对应的命令字符串。关键细节在 spawn.js 第 14 行执行事件命令时会把eventArgs[0]即触发事件的首个文件路径注入环境变量FILENAME——这正是示例中$FILENAME的来源。因此你可以用同样的机制实现重启后跑测试崩溃后发报警等自动化。若希望完全接管子进程的 stdout/stderr 输出流例如把日志重定向到文件可以配合stdout: false使用readable事件相关用法可参考 doc/events.md 与 README 中的 Pipe output to somewhere else 一节。6.watch限定要监听的目录 / 文件watch: [ test/fixtures/, test/samples/ ]默认情况下 nodemon 监听当前工作目录的全部文件默认watch: [*.*]见 defaults.js 第 16 行。一旦配置了watch监听范围就收窄为列出的路径——示例中的配置意味着只有当test/fixtures/或test/samples/下的文件发生变化时才会触发重启非常适合改测试文件自动跑测试的开发场景。从实现看lib/monitor/match.js 的rulesToMonitor会把watch中的目录解析为绝对路径并展开为dir/**/*形式同时把 ignore 规则以!前缀附加到监控列表最终通过 minimatch 对变更文件做匹配。命令行等价写法是--watch app --watch libs可多次使用也支持带引号的 glob如--watch ./lib/*。注意 watch 规则同样支持单文件路径nodemon 会对单文件做精确监听。7.env注入子进程的环境变量env: { NODE_ENV: development }env中的键值对会合并进被监听子进程的环境变量。在 lib/config/exec.js 第 231–237 行nodemon 会校验env必须是普通对象否则抛出nodemon env values must be an object: { PORT: 8000 }错误随后该对象被克隆进execOptions.env。真正落地时lib/monitor/run.js 第 66–74 行会用Object.assign({}, options.execOptions.env, process.env, {...PATH...})组合出子进程的完整环境并把当前项目的node_modules/.bin追加进PATH。常见的实战用法包括注入NODE_ENV、PORT、DEBUG等从而做到配置文件即环境开关。8.ext扩展名监听白名单ext: js,jsonext决定哪些扩展名的文件变更会触发重启。默认行为与脚本扩展名联动lib/config/exec.js 第 123–128 行监听.js脚本时默认扩展为js,mjs,cjs并始终附加json若执行的是.py脚本则会自动改为监听py。示例中显式指定js,json表示只关心这两类文件。值得注意的细节当使用--exec运行非 Node 脚本时nodemon 会自动切换到该脚本的扩展名因此通常无需手动设置ext。在 lib/monitor/match.js 第 254–265 行扩展名列表最终会被编译为**/*.{js,json}形式的 glob用于过滤匹配到的文件。命令行等价写法是-e js,pug如nodemon -e js,pug表示.js与.pug文件变更都会触发重启。四、配置加载与合并的完整链路理解配置文件在启动时如何被处理有助于排查为什么我的配置没生效。整条链路位于 lib/config/load.js读取全局配置从用户主目录读取nodemon.json若不存在则跳过读取本地配置从process.cwd()读取nodemon.json若本地没有该文件会回退尝试package.json中的nodemonConfig字段load.js 第 159–166 行的loadPackageJSON若指定了--config file则以该文件替代本地nodemon.json合并命令行设置options utils.merge(settings, options)命令行参数优先处理 ignore兼容旧版非数组写法单个字符串会被包成数组并把默认 ignoreRoot 与用户 ignore 合并补齐默认值utils.merge(options, defaults)填入未设置的默认项自动发现脚本若既没有 script 也没有 exec会尝试读取package.json的main字段或回退到当前目录的index.jsfindAppScript生成执行选项mutateExecOptions调用 lib/config/exec.js 的exec()解析出execOptions含 exec、args、ext、env 等规则归一化normaliseRules把 watch / ignore 规则交给 lib/rules/add.js 编译为内部规则结构。同时nodemon 会把解析出的options.configFile记录进config.loaded以去重并在config:update事件触发时感知配置变更。五、验证与调试--dump 与 --verbose配置写完后可以用两个命令行开关快速验证最终生效的配置nodemon --dump打印完整的调试配置解析后的全部 options 与 execOptions是核对配置到底长什么样的最直接手段参见 doc/cli/options.txt 中--dump的说明解析逻辑在 lib/cli/parse.js 第 124–126 行nodemon --verbose-V运行期输出详细日志展示每一条匹配/忽略规则的判定结果。六、延伸package.json 的 nodemonConfig 与配置参考如果你希望把所有包配置收敛到一个文件里可以用package.json的nodemonConfig字段承载同样的配置例如{ name: my-app, nodemonConfig: { ignore: [**/test/**, **/docs/**], delay: 2500 } }注意两点其一若存在本地nodemon.json或显式--config文件package.json中的nodemonConfig会被忽略README 与 load.js 均如此说明其二配置文件中delay的数值一律按毫秒解释而命令行--delay 2.5则按秒解释两者不可混用。仓库 test/fixtures/configs/top-level.json 中还有一份真实可用的配置样例包含watch、ext、exec等键可以作为编写自定义配置的参考README.md 的 Config files 一节则给出了更多execMap与忽略规则的实战示例。结语一份精心编写的nodemon.json可以把监听范围、忽略规则、执行方式、环境变量、重启动作全部声明化让团队所有成员的开发体验保持一致。理解示例文件中 8 个配置键的语义与默认行为掌握命令行 本地配置 全局配置的优先级再配合--dump进行验证你就能从会用 nodemon进阶到精确掌控 nodemon。【免费下载链接】nodemonMonitor for any changes in your node.js application and automatically restart the server - perfect for development项目地址: https://gitcode.com/gh_mirrors/no/nodemon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 nodemon.json 配置完全指南：基于官方示例文件逐项解读 nodemon 的核心配置项
nodemon.json 配置完全指南基于官方示例文件逐项解读 nodemon 的核心配置项【免费下载链接】nodemonMonitor for any changes in your node.js application and automatically restart the server - perfect for development项目地址: https://gitcode.com/gh_mirrors/no/nodemon导读nodemon.json是 nodemon 的配置文件用于把监听哪些文件、何时重启、用什么命令执行、注入什么环境变量等开发期行为固化下来。本文以 nodemon 仓库官方文档 doc/sample-nodemon.md 中的示例文件为骨架逐项拆解restartable、ignore、verbose、execMap、events、watch、env、ext这 8 个配置键的语义、默认值与底层实现并结合 lib/config/defaults.js、lib/config/load.js、lib/monitor/run.js 等源码说明它们如何真实生效。读完本文你将能够读懂并编写一份可投入实战的 nodemon 配置文件并掌握配置优先级与调试验证手段。一、nodemon.json 的角色配置文件从哪来、谁覆盖谁nodemon 支持在项目目录当前工作目录和用户主目录放置nodemon.json配置文件也支持通过--config file指定任意位置的替代配置文件。配置文件可以承载任何命令行参数的 JSON 形式。配置的生效优先级高到低为命令行参数——始终覆盖配置文件本地配置——当前工作目录下的nodemon.json全局配置——用户主目录下的nodemon.json。这一规则在 lib/config/load.js 的load函数中有明确的实现顺序先读取utils.home下的全局配置再读取process.cwd()下的本地配置最后用命令行解析出的 settings 通过utils.merge(settings, options)合并覆盖merge 保护已有值因此命令行参数优先级最高见 load.js 中注释。二、示例文件全貌官方示例一个刻意编排的演示性配置如下本文后续所有小节都围绕它展开{ restartable: rs, ignore: [ .git, node_modules/**/node_modules ], verbose: true, execMap: { js: node --harmony }, events: { restart: osascript -e display notification \App restarted due to:\n$FILENAME\ with title \nodemon\ }, watch: [ test/fixtures/, test/samples/ ], env: { NODE_ENV: development }, ext: js,json }三、逐项解读 8 个核心配置键1.restartable手动触发重启的命令restartable: rsnodemon 运行期间你可以在终端输入该字符串并回车强制重启当前监听的子进程而不必退出 nodemon 再重新启动。默认值正是rs见 lib/config/defaults.js 第 5 行restartable: rs。在 lib/monitor/run.js 中子进程退出后会检查config.options.restartable并重新process.stdin.resume()以便继续监听标准输入中的重启命令而bus.on(restart)监听器会调用run.kill()杀掉子进程树再由子进程的exit事件处理器触发重启。这也解释了手动重启是走杀进程 → 重新拉起的完整链路而非原地热更新。2.ignore忽略文件 / 目录规则ignore: [ .git, node_modules/**/node_modules ]官方文档特别注明示例中的ignore用的正是 nodemon 的默认忽略规则。nodemon 默认忽略.git、node_modules、bower_components、.nyc_output、coverage、.sass-cache等目录这些目录来自ignore-by-default包并统一转换为**/dir/**形式的 glob 规则即 lib/config/defaults.js 第 15 行的ignoreRoot。关键点在于你配置的ignore不会替换默认忽略项而是与之合并。在 lib/config/load.js 第 62–69 行nodemon 会先把options.ignoreRoot默认忽略与用户options.ignore拼接成同一个数组再统一交给规则引擎。也就是说即使你的配置文件里写的是node_modules/**/node_modules这种嵌套规则.git等默认目录依然会被忽略。若确实想监听node_modules之类的默认忽略目录需要显式覆盖底层 ignoreRoot 规则。从匹配实现看lib/monitor/match.js所有 watch / ignore 规则都会以绝对路径 minimatch 进行匹配dot: trueWindows 下开启nocaseignore 规则以!前缀叠加在 watch 规则之后且 ignore 规则在排序中优先级最高见match函数中的排序逻辑。3.verbose输出导致重启的详细原因verbose: true默认值为falselib/config/defaults.js 第 19 行。开启后nodemon 会输出哪条规则匹配了哪个文件、为什么触发重启等细节。在 lib/config/load.js 第 102–104 行配置加载完成后若options.verbose为真会把utils.debug置为true而匹配器lib/monitor/match.js中大量utils.log.detail(matched rule: ...)之类的调试输出正是依赖这个开关。命令行等价写法是-V/--verbose。4.execMap按扩展名映射可执行程序execMap: { js: node --harmony }execMap用于建立文件扩展名 → 执行命令的映射使得nodemon xxx.ext时无需显式--exec也能找到正确的解释器。nodemon 内置的默认映射lib/config/defaults.js 第 7–14 行包括扩展名默认执行程序pypythonrbrubytsts-node注意当环境变量NODE_OPTIONS中包含--loader或--import时默认的ts映射会被删除defaults.js 第 28–32 行以避免与 Node 的 ESM loader 机制冲突。在 lib/config/exec.js 第 135–138 行只有当用户没有显式指定exec时nodemon 才会回退到execMap[scriptExt]因此execMap是兜底而非强制。示例中的js: node --harmony属于演示性写法--harmony是早期 Node 的 harmony 特性开关在真实项目中你更可能像这样扩展非默认语言{ execMap: { pl: perl, pde: processing --sketch{{pwd}} --run } }execMap的值还支持{{filename}}与{{pwd}}变量替换exec.js 第 150–164 行其中{{pwd}}会被替换为process.cwd()。官方建议把自定义的execMap放在全局nodemon.json这样所有项目都能受益。5.events在 nodemon 状态变化时执行外部命令events: { restart: osascript -e display notification \App restarted due to:\n$FILENAME\ with title \nodemon\ }events允许把 nodemon 的生命周期事件绑定到一段 shell 命令。示例在 macOS 上通过osascript在每次重启时弹出一条系统通知通知内容中通过$FILENAME引用触发重启的文件。实现上nodemon 通过事件总线bus广播事件事件种类详见 doc/events.md包括命令类restart、config:update、quit状态类start子进程启动、crash子进程崩溃此时不触发exit、exit子进程正常退出、restart传入触发重启的文件数组消息类log、stdout、stderr、readable。在 lib/nodemon.js 第 233–244 行配置加载完成后nodemon 会遍历config.options.events的每个键用nodemon.on(key, ...)绑定事件并在触发时通过 lib/spawn.js 以子进程方式执行对应的命令字符串。关键细节在 spawn.js 第 14 行执行事件命令时会把eventArgs[0]即触发事件的首个文件路径注入环境变量FILENAME——这正是示例中$FILENAME的来源。因此你可以用同样的机制实现重启后跑测试崩溃后发报警等自动化。若希望完全接管子进程的 stdout/stderr 输出流例如把日志重定向到文件可以配合stdout: false使用readable事件相关用法可参考 doc/events.md 与 README 中的 Pipe output to somewhere else 一节。6.watch限定要监听的目录 / 文件watch: [ test/fixtures/, test/samples/ ]默认情况下 nodemon 监听当前工作目录的全部文件默认watch: [*.*]见 defaults.js 第 16 行。一旦配置了watch监听范围就收窄为列出的路径——示例中的配置意味着只有当test/fixtures/或test/samples/下的文件发生变化时才会触发重启非常适合改测试文件自动跑测试的开发场景。从实现看lib/monitor/match.js 的rulesToMonitor会把watch中的目录解析为绝对路径并展开为dir/**/*形式同时把 ignore 规则以!前缀附加到监控列表最终通过 minimatch 对变更文件做匹配。命令行等价写法是--watch app --watch libs可多次使用也支持带引号的 glob如--watch ./lib/*。注意 watch 规则同样支持单文件路径nodemon 会对单文件做精确监听。7.env注入子进程的环境变量env: { NODE_ENV: development }env中的键值对会合并进被监听子进程的环境变量。在 lib/config/exec.js 第 231–237 行nodemon 会校验env必须是普通对象否则抛出nodemon env values must be an object: { PORT: 8000 }错误随后该对象被克隆进execOptions.env。真正落地时lib/monitor/run.js 第 66–74 行会用Object.assign({}, options.execOptions.env, process.env, {...PATH...})组合出子进程的完整环境并把当前项目的node_modules/.bin追加进PATH。常见的实战用法包括注入NODE_ENV、PORT、DEBUG等从而做到配置文件即环境开关。8.ext扩展名监听白名单ext: js,jsonext决定哪些扩展名的文件变更会触发重启。默认行为与脚本扩展名联动lib/config/exec.js 第 123–128 行监听.js脚本时默认扩展为js,mjs,cjs并始终附加json若执行的是.py脚本则会自动改为监听py。示例中显式指定js,json表示只关心这两类文件。值得注意的细节当使用--exec运行非 Node 脚本时nodemon 会自动切换到该脚本的扩展名因此通常无需手动设置ext。在 lib/monitor/match.js 第 254–265 行扩展名列表最终会被编译为**/*.{js,json}形式的 glob用于过滤匹配到的文件。命令行等价写法是-e js,pug如nodemon -e js,pug表示.js与.pug文件变更都会触发重启。四、配置加载与合并的完整链路理解配置文件在启动时如何被处理有助于排查为什么我的配置没生效。整条链路位于 lib/config/load.js读取全局配置从用户主目录读取nodemon.json若不存在则跳过读取本地配置从process.cwd()读取nodemon.json若本地没有该文件会回退尝试package.json中的nodemonConfig字段load.js 第 159–166 行的loadPackageJSON若指定了--config file则以该文件替代本地nodemon.json合并命令行设置options utils.merge(settings, options)命令行参数优先处理 ignore兼容旧版非数组写法单个字符串会被包成数组并把默认 ignoreRoot 与用户 ignore 合并补齐默认值utils.merge(options, defaults)填入未设置的默认项自动发现脚本若既没有 script 也没有 exec会尝试读取package.json的main字段或回退到当前目录的index.jsfindAppScript生成执行选项mutateExecOptions调用 lib/config/exec.js 的exec()解析出execOptions含 exec、args、ext、env 等规则归一化normaliseRules把 watch / ignore 规则交给 lib/rules/add.js 编译为内部规则结构。同时nodemon 会把解析出的options.configFile记录进config.loaded以去重并在config:update事件触发时感知配置变更。五、验证与调试--dump 与 --verbose配置写完后可以用两个命令行开关快速验证最终生效的配置nodemon --dump打印完整的调试配置解析后的全部 options 与 execOptions是核对配置到底长什么样的最直接手段参见 doc/cli/options.txt 中--dump的说明解析逻辑在 lib/cli/parse.js 第 124–126 行nodemon --verbose-V运行期输出详细日志展示每一条匹配/忽略规则的判定结果。六、延伸package.json 的 nodemonConfig 与配置参考如果你希望把所有包配置收敛到一个文件里可以用package.json的nodemonConfig字段承载同样的配置例如{ name: my-app, nodemonConfig: { ignore: [**/test/**, **/docs/**], delay: 2500 } }注意两点其一若存在本地nodemon.json或显式--config文件package.json中的nodemonConfig会被忽略README 与 load.js 均如此说明其二配置文件中delay的数值一律按毫秒解释而命令行--delay 2.5则按秒解释两者不可混用。仓库 test/fixtures/configs/top-level.json 中还有一份真实可用的配置样例包含watch、ext、exec等键可以作为编写自定义配置的参考README.md 的 Config files 一节则给出了更多execMap与忽略规则的实战示例。结语一份精心编写的nodemon.json可以把监听范围、忽略规则、执行方式、环境变量、重启动作全部声明化让团队所有成员的开发体验保持一致。理解示例文件中 8 个配置键的语义与默认行为掌握命令行 本地配置 全局配置的优先级再配合--dump进行验证你就能从会用 nodemon进阶到精确掌控 nodemon。【免费下载链接】nodemonMonitor for any changes in your node.js application and automatically restart the server - perfect for development项目地址: https://gitcode.com/gh_mirrors/no/nodemon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考