Repomix 内存泄漏检测与基准测试实战：scripts/memory 工具链完全指南

Repomix 内存泄漏检测与基准测试实战scripts/memory 工具链完全指南【免费下载链接】repomix Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix本篇指南围绕 Repomix 仓库内置的内存基准测试工具scripts/memory展开介绍如何通过重复调用runCli打包流程、采样堆内存Heap与 RSS从而判断 Repomix 在处理大规模仓库时是否存在内存泄漏。读完本文你将掌握该工具的环境搭建、全部命令行参数、结果解读标准包括预热基线对比方法并了解其与主仓库 src/cli/cliRun.ts 的底层调用关系可直接在自己的开发与 CI 流程中复用它来守护 Repomix 的内存稳定性。工具定位为什么 Repomix 需要专门的内存基准测试Repomix 的核心职责是把整个仓库打包成一个适合 LLM 消费的单一文件。在实际使用场景中它可能面临几种持续占用内存的压力打包包含海量文件的巨型仓库include/ignore过滤、文件读取、树形结构生成、Token 计数等环节都会分配内存--watch模式下的持续监听与重复打包以 MCP Server 方式常驻进程、被 Agent 反复调用见 src/mcp/mcpServer.ts。一旦某条调用链上存在对象未被正确释放内存就会随调用次数线性增长最终导致 OOM 或服务不可用。scripts/memory工具正是为此设计它在同一进程内反复执行完整的 Repomix 打包流程周期性采样内存指标并做趋势分析用数据化的方式回答内存到底稳不稳定。该工具的说明文档为 scripts/memory/README.md核心实现位于 scripts/memory/src/memory-test.ts类型定义在 scripts/memory/src/types.ts。环境准备与安装前置条件从 scripts/memory/package.json 的engines字段可以看到engines: { node: 22.0.0 }即要求Node.js 22.0.0 或更高版本同时需要包管理器npm。另外由于测试脚本依赖--expose-gc强制触发垃圾回收详见下文运行环境必须支持该 Node 启动参数标准 Node 均支持。安装依赖文档给出的安装方式为cd scripts/memory npm install安装过程会同时拉取两类依赖运行依赖asciichart终端 ASCII 图表绘制及其类型声明types/asciichart以及repomix: file:../..—— 即通过本地文件链接引用仓库根目录的 Repomix 主包无需单独发布或下载开发依赖types/node、typescript用于编译 TypeScript 源码。编译构建本工具是 TypeScript 项目运行前需要先编译。包内提供三个构建脚本npm run build # 仅编译本工具tsc输出到 dist/ npm run build:repomix # 仅构建主仓库cd ../.. node --run build npm run build:all # 先构建 Repomix 主项目再编译本工具在全新克隆的仓库中建议直接使用npm run build:all确保file:../..引用的 Repomix 主包已是最新构建产物编译配置见 scripts/memory/tsconfig.json输出目录为dist/模块方案为 NodeNext。快速开始通过 npm scripts 运行当前 package.json 实际入口scripts/memory/package.json 中当前定义了三个测试入口它们都会先执行build:all再以--expose-gc启动编译产物npm run test # node --run build:all node --expose-gc dist/memory-test.js npm run test:full # ... dist/memory-test.js --full npm run test:continuous # ... dist/memory-test.js --continuousnpm run test默认模式快速内存泄漏检查npm run test:full完整分析模式迭代更多、采样更密、输出更详细npm run test:continuous连续监控模式一直运行直到CtrlC中断。文档记录的脚本与现状差异说明值得注意原文档 scripts/memory/README.md 中记录的脚本名为leak:quick、leak:watch、leak:analyze分别对应快速泄漏检测 20 次迭代、持续监控、带报告的综合分析而当前 scripts/memory/package.json 中实际定义的是test/test:full/test:continuous。从源码核对scripts/memory/src/memory-test.ts可知leak:quick/leak:analyze的功能分别与默认模式和--full模式对应leak:watch与--continuous对应README 的脚本名属于文档与配置的漂移以 package.json 当前脚本为准即可获得相同能力。文档中20 次迭代的描述也与源码默认值basic 100 次不一致同样以源码为准详见下文参数说明。命令行参数详解编译后的测试程序dist/memory-test.js支持完整的命令行参数帮助信息通过--help查看。参数解析逻辑见 scripts/memory/src/memory-test.ts。位置参数node --expose-gc dist/memory-test.js [iterations] [delay] [options]参数含义默认值iterations测试迭代次数正整数basic 模式100--full模式200delay每轮迭代之间的等待毫秒数非负basic 模式50ms--full模式100ms注意帮助文本中写的是basic 默认 50 次但源码实际默认值为flags.full ? 200 : 100memory-test.ts请以源码行为为准。选项选项简写作用--full-f综合模式更多迭代、更密集采样与周期性趋势分析--continuous—连续运行直到CtrlC在 CI 环境非 full下超过 60 秒自动停止--save-s将详细结果保存为 JSON 文件--full模式下默认也会保存--help-h显示帮助并退出模式相关的内部常量不同模式下采样与判定参数也会联动调整memory-test.ts常量basic 模式--full模式MEMORY_LOG_INTERVAL每 N 轮记录一次内存510FORCE_GC_INTERVAL每 N 轮强制 GC2050WARNING_THRESHOLD内存增长告警百分比100%50%常用组合示例# 默认快速检测100 次迭代50ms 间隔 node --expose-gc dist/memory-test.js # 综合检测200 次迭代100ms 间隔并把结果存为 JSON node --expose-gc dist/memory-test.js --full # 自定义100 次迭代、每次间隔 200ms node --expose-gc dist/memory-test.js 100 200 # 连续监控直到 CtrlC 停止 node --expose-gc dist/memory-test.js --continuous启动时会校验参数迭代次数必须是正数、delay 必须非负否则直接报错退出memory-test.ts。测试执行流程从 runCli 到趋势分析被测负载每个迭代执行一次完整打包工具通过TEST_CONFIG定义每一轮迭代要执行的任务memory-test.tsconst TEST_CONFIG: TestConfig { name: Memory Test, args: [.], cwd: projectRoot, options: { include: src/**/*.ts, output: path.join(__dirname, ../test-output.txt), compress: true, quiet: true, }, };即对scripts/memory目录执行一次 Repomix 打包include只收集src/**/*.ts输出到test-output.txt开启压缩并静默输出。每轮的核心调用是await runCli(TEST_CONFIG.args, TEST_CONFIG.cwd, TEST_CONFIG.options);runCli正是 Repomix 的主入口定义于 src/cli/cliRun.tsrunCli async (directories: string[], cwd: string, options: CliOptions)。它内部会处理 stdout 模式检测、日志级别设置、--watch参数校验、sandbox 与 MCP 分支最终落入打包动作该函数也从 src/index.ts 作为公共 API 导出说明内存测试走的是与真实 CLI 完全相同的代码路径——这正是内存结论可信的关键。主循环骨架主循环逻辑见 memory-test.ts每个迭代依次执行调用runCli执行打包调用cleanupFiles删除上一轮生成的test-output.txt避免磁盘累积也避免输出写入路径干扰结果若本轮为MEMORY_LOG_INTERVAL的整数倍或出现错误则记录一次内存快照若本轮为FORCE_GC_INTERVAL的整数倍则调用forceGC()手动触发一次全量垃圾回收--full模式下在超过 20 轮后每MEMORY_LOG_INTERVAL * 2轮做一次中间趋势分析按delay休眠--continuous且非--full时超过 60 秒CI 时间上限自动终止。强制 GC让测量更干净function forceGC(): void { if (global.gc) { global.gc(); console.log(️ Forced garbage collection); } }global.gc只有在以--expose-gc启动 Node 时才会存在。周期性强制 GC 的目的是把可达对象与垃圾但尚未被回收的对象区分开如果不主动 GC堆的增长可能只是回收延迟造成的假象而非真实泄漏。结果解读Heap 与 RSS采样字段每次采样通过process.memoryUsage()获取指标memory-test.ts换算成 MB 并记录字段含义说明heapUsed堆内存已用部分JavaScript 对象实际占用理想情况下应趋于稳定heapTotalV8 分配的堆总量堆容量会随需要扩张external堆外内存如 Buffer/字符串外存等rss进程常驻内存整个进程占用含堆、代码、栈、模块缓存等关注增长 100%heapUsagePercentheapUsed / heapTotal堆使用率百分比文档 scripts/memory/README.md 给出的判读口诀是Heap Memory由 JavaScript 对象构成应当趋于稳定stabilizeRSS Memory进程总内存需警惕超过 100% 的增长。如果两条曲线都出现持续单边上升说明存在内存泄漏如果稳定后仅小幅波动则属于正常现象。输出样例每次记录会打印对齐格式的状态行✅/❌表示该轮成功/出错✅ Iteration 20: Memory Test - Heap: 45.23MB/ 78.10MB ( 57.92%), RSS: 189.34MB ❌ Iteration 30: Memory Test - Heap: 50.11MB/ 82.00MB ( 61.11%), RSS: 195.67MB (ERROR: ...)自动判定与退出码测试结束时工具会对比预热后的基线与最近 5 轮的平均值memory-test.ts Final Memory Analysis (post-warmup baseline vs final): Baseline (avg 21–25): Heap 44.10MB, RSS 186.20MB Final (avg last 5): Heap 45.02MB, RSS 188.90MB Growth: Heap 2.09%, RSS 1.45% ✅ Memory usage appears stable若 Heap 或 RSS 的增长百分比超过阈值basic 100%、--full50%会打印⚠️ WARNING: Significant memory growth detected!并将process.exitCode置为 1memory-test.ts。这意味着内存测试可以直接作为 CI 门禁内存泄漏时流水线失败。为什么必须用预热后基线对比工具刻意避免用冷启动 vs 最终的粗暴对比原因在源码注释中说明得很清楚memory-test.ts前约 20% 的迭代属于warmup 阶段此时内存增长的主要来源是V8 JIT 即时编译产生的代码缓存模块系统ESM/依赖图的首次加载与缓存V8 堆的初始扩张heap expansion。这些都是一次性成本并非泄漏。如果拿冷启动值与最终值对比任何正常运行的程序都会显示大幅增长从而产生误报。因此工具采用将历史记录的前 20% 视为 warmupwarmupCount max(1, floor(len * 0.2))以 warmup 之后的连续样本作为基线趋势分析取 10 条最终分析取 5 条与最后 5~10 条样本求平均对比计算增长百分比。同样的逻辑在analyzeMemoryTrendsmemory-test.ts中以post-warmup模式定期执行保证中间报告与最终结论口径一致。图表、报告与结果持久化终端 ASCII 图表当采样点不少于 5 个时工具会使用asciichart在终端绘制内存曲线memory-test.ts分别输出Heap Usage (MB)与RSS Usage (MB)两张图默认取最近 40 个点、图表高度 8 行。通过曲线形态可以直观判断是稳定平台还是持续爬升。保存 JSON 报告使用--save或--full模式自动触发时结果会写入scripts/memory/memory-test-results-时间戳.jsonmemory-test.ts。文件结构对应 scripts/memory/src/types.ts 中的MemoryTestSummary{ testInfo: { iterations: 100, startTime: …, endTime: … }, memoryHistory: [ { iteration: 0, configName: Memory Test, timestamp: …, heapUsed: 12.34, heapTotal: 30.0, external: 1.2, rss: 80.5, heapUsagePercent: 41.13, error: false } ], analysis: { peakHeapUsage: 45.23, peakRSSUsage: 189.34, errorCount: 0, averageHeapUsage: 40.1, averageRSSUsage: 175.2 } }完整历史序列 统计摘要的组合方便接入外部监控或生成可视化报告。安全退出与异常处理工具注册了SIGINT与uncaughtException处理器memory-test.ts用户中断CtrlC或未捕获异常时都会先保存已采样的内存历史、清理输出文件再退出避免长时间测试的数据丢失。与主仓库的联动及周边性能工具scripts/memory并非孤立存在它与其他性能设施共同构成 Repomix 的性能守卫体系公共 API 复用测试直接调用 src/index.ts 导出的runCli与 CLI、MCP 走同一条打包链路测量结果对真实使用场景有代表性主仓库快速检查脚本根目录 package.json 提供memory-checknode --run repomix -- --verbose | grep Memory与memory-check-one-file针对单个文件--include package.json的最小化检查适合日常快速验证CPU 基准脚本scripts/bench-cores.sh 使用hyperfinetaskset测试不同 CPU 核数下的打包耗时与内存测试互补分别覆盖快不快与稳不稳两个维度。常见问题与判定参考现象原因与处理Invalid iterations count/Invalid delay位置参数不合法迭代次数须为正整数、delay 须非负memory-test.ts输出Too few data points for reliable analysis采样点不足 10 个无法做趋势分析适当增加迭代次数global.gc不可用必须用node --expose-gc启动npm scripts 已内置该参数最终WARNING: Significant memory growth detected!Heap 或 RSS 增长超阈值basic 100%、full 50%exitCode 1需结合图表定位泄漏调用链CI 中连续模式自动停止--continuous且非--full时 60 秒时间上限触发memory-test.ts避免 CI 挂死总结来说scripts/memory是一套开箱即用的内存泄漏检测工具以真实runCli打包流程为负载通过process.memoryUsage()采样 Heap/RSS、周期性强制 GC、warmup 后基线对比与终端图表给出可量化、可接入 CI 的稳定性结论。当你在 Repomix 上新增功能或处理大仓库场景时npm run test:full就能为内存安全提供一道可靠防线。【免费下载链接】repomix Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考