NestJS Module Trace

一个可以插入到任意 NestJS 应用中的插件，用来统计当前应用里注册了多少个模块，并且以树形结构展示模块之间的父子（导入）关系。

特性

• 自动扫描当前 Nest 容器中的所有模块
• 统计模块总数，并构建父子依赖树
• 支持检测循环依赖并在输出中高亮
• 可配置的自动打印、日志器、最大遍历深度、彩色输出

安装

npm install nestjs-module-trace

快速上手

在根模块中引入 ModulesTraceModule。默认情况下你可以调用 forRoot() 开启自动日志输出，或者手动注入 ModulesTraceService 使用。

import { ModulesTraceModule } from 'nestjs-module-trace';

@Module({
  imports: [
    // 自动打印模块树
    ModulesTraceModule.forRoot({
      autoLog: true,
    }),
    AppModule,
  ],
})
export class BootstrapModule {}

也可以在任意 provider 中注入 ModuleTraceService，自行处理统计数据：

import { Injectable, OnModuleInit } from '@nestjs/common';
import { ModulesTraceService } from 'nestjs-module-trace';

@Injectable()
export class DiagnosticsService implements OnModuleInit {
  constructor(private readonly modulesTrace: ModulesTraceService) {}

  onModuleInit() {
    const total = this.modulesTrace.getModuleCount();
    const tree = this.modulesTrace.getModuleTree();

    // 自定义处理逻辑
    console.log(`Nest 应用共包含 ${total} 个模块`);
    console.dir(tree, { depth: null });
  }
}

配置项

| 选项 | 类型 | 默认值 | 说明 | | ---------------------- | ------------ | -------------------------- | ---------------------------------------------------------------- | | autoLog | boolean | false | 启动时是否自动打印模块树 | | colorize | boolean | true | 控制终端输出是否使用颜色 | | maxDepth | number | undefined | 限制遍历深度，防止超大项目输出过长 | | includeInternals | boolean | false | 是否保留 Nest 内部模块（DiscoveryModule、InternalCoreModule 等） | | excludeModuleNames | string[] | ["ModulesTraceModule"] | 主动排除的模块名字列表（默认不显示本插件自身） | | logger | Console | console | 自定义日志器，实现 log() 方法即可 |

发布到 npm

本仓库已添加若干方便发布到 npm 的脚本，位于 package.json 的 scripts：

• prepublishOnly: 在发布前确保运行 npm run build。
• publish:public: 以 --access public 发布（适用于非 scoped 或公开包）。
• release:patch|minor|major: 自动调整版本并执行 npm publish（会创建 git 提交与 tag）。

常用发布流程（在命令行执行）：

# 登录 npm
npm login

# 提升补丁版本并发布
npm run release:patch

# 或者手动：
npm version patch
npm publish --access public

注意事项：

• 如果你的 npm 账号启用了 2FA（双重验证），npm publish 可能会要求输入一次性验证码。可以使用 npm version 本地更新版本，然后运行 npm publish 手动输入验证码。
• npm version 会创建一个 git 提交并打 tag；如果你不希望这样，请使用 npm version --no-git-tag-version。
• 在首次发布前请确认 name、version、repository 等 package.json 字段正确。

如果你希望我代为准备发布（比如 bump version、打 tag、或生成发布说明），告诉我你希望的版本策略，我可以继续操作或给出更详细步骤。

输出示例

[ModulesTrace] Detected 5 modules.
└─ AppModule (2 imports)
   ├─ SharedModule
   └─ UsersModule (2 imports)
      ├─ PrismaModule
      └─ SharedModule (circular)

运行示例

仓库内提供了 examples/basic，模拟了一个小型 Nest 应用。执行下列命令即可看到插件打印出的模块树：

npm run example

命令会通过 ts-node 启动应用、自动打印模块关系，并再次调用 ModuleTraceService.printSummary() 与 getModuleCount()，方便你验证输出效果。

如果想要更易于阅读 / 分享的 Markdown 版本，运行：

npm run example:md

脚本会在 examples/basic/modules-trace.md 下生成一份层级清晰的树状文档，便于直接贴到文档或 PR 说明中。

开发

npm install
npm run build
npm run lint