repomix

你会遇到什么

这个工具解决什么问题：把整个仓库塞进 AI 上下文。Repomix 把仓库打包成单个文件，带 token 预算控制（--compress 压缩），让 AI 一次性看全貌——做审查、写文档、跨仓库分析时的输入侧工具。 什么时候用：

• 你要把仓库（或指定子集）打包给 AI 分析；
• 你要控制 token 预算（大仓库 --compress + --include 限定范围）；
• 你要单文件输出便于分享/存档。

什么时候别用：仓库太大且不需要全量时——用 --include 限范围；或只需要单个文件内容时，直接给文件即可。 和相邻工具的边界：输入侧工具，不写用户级配置、无后台进程；输出单文件写当前目录（默认 repomix-output.txt，建议 .gitignore）。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

它怎么工作：npm 全局包（Node >= 18），或免安装 npx -y repomix <目录>。在目标仓库根目录执行：repomix . --compress --output repomix-output.txt 生成单文件 + Pack Summary（Total Files / Total Tokens / Output 路径）。可选 --include 限定 glob、--init 生成配置（--init 写面未实测）。 关键概念：

• --compress：压缩打包（实测通过）；
• --include：范围限定（官方功能，未实测）；
• --output：输出路径（实测生效）。

装完它动哪里：不写用户级配置；输出文件写当前目录（或 --output 指定路径）；npx 缓存落 ~/.npm（免安装形态）。

一步步来

第 1 步：装 CLI（为什么全局装：npx 免安装也行，但全局更稳）

讲解：npm 全局装（国内用 npmmirror 前缀，2026-08-29 实测秒装）；免安装形态 npm_config_registry=https://registry.npmmirror.com npx -y repomix <目录> 同样可用。单二进制 Release 与 brew（macOS）未实测。

npm_config_registry=https://registry.npmmirror.com npm install -g repomix
repomix --version

预期输出: 1.18.0

装好确认：

• --version 输出 1.18.0；
• Node >= 18。

卡住怎么办：

• npm 慢 → 确认带 npmmirror 前缀；
• Node 版本 → 确认 >= 18。

第 2 步：打包第一个仓库（本环境实测）

讲解：在目标仓库根目录执行。--compress 压缩 token；--output 指定输出路径（默认 repomix-output.txt）。实测 2 文件 → 1983 字符输出。

repomix . --compress --output repomix-output.txt

预期输出: Pack Summary（Total Files / Total Tokens / Output 路径；2026-08-29 实测 2 文件 → 1983 字符）

装好确认：

• Pack Summary 正常输出；
• 输出文件存在（默认当前目录 repomix-output.txt）。

卡住怎么办：

• 输出文件进 git → 建议加入 .gitignore（打包文件不该入库）；
• 打包慢 → 大仓库用 --include 限范围。

第 3 步：控制范围与 token 预算

讲解：--include 限定打包范围（官方功能，未实测）；--output 换输出路径（实测生效）。大仓库实测 站内文档 全目录 → 62KB/959 行单文件。

repomix . --compress --include "src/**/*.ts,README.md"

预期输出: 只打包匹配的文件（--compress 实测通过；--include 为官方功能，未实测）

repomix . --output /tmp/repo-context.txt

预期输出: 单文件写入指定路径（2026-08-29 实测 --output 生效）

卡住怎么办：

• --include 行为不符 → 该参数为官方功能（未实测），以 --help/官方文档为准；
• 输出路径不可写 → 换可写目录（--output）。

怎么确认修好了

第 1 步：确认打包链路

讲解：repomix . --compress --output repomix-output.txt 跑完有 Pack Summary 且输出文件存在，说明打包链路完整可用。

repomix . --compress --output repomix-output.txt
ls -l repomix-output.txt

预期输出: Pack Summary（Total Files / Total Tokens / Output 路径）+ 输出文件存在（2026-08-29 实测 2 文件 → 1983 字符）

卡住怎么办：

• Pack Summary 报错 → 确认在目标仓库根目录执行、目录可读；
• 输出文件进 git → 把 repomix-output.txt 加进 .gitignore（打包文件不该入库）。

第 2 步：确认范围控制生效

讲解：--output 换路径实测生效；--include 限定范围是官方功能（未实测）——两者能限制「打包进上下文的内容」。

repomix . --output /tmp/repo-context.txt
ls -l /tmp/repo-context.txt

预期输出: 单文件写入指定路径（--output 实测生效）

卡住怎么办：

• --include 行为不符 → 该参数为官方功能（未实测），以 --help/官方文档为准；
• 输出路径不可写 → 换可写目录（--output）。

其它环境的表现（常见变体）

• Node 版本：要求 >= 18（npm/npx 形态）；官方还提供免 Node 的单二进制 Release（本机未实测）。
• Windows / macOS：npm 安装与命令一致（国内用 npmmirror 前缀，实测秒装）。
• 写面：不写用户级配置；输出单文件写当前目录（默认 repomix-output.txt，建议 .gitignore）。
• 与其它工具共装：与 code-review-graph / swe-rex 判定 possible-compatible——写面不重叠（输出文件 / 审查报告 / 修复 diff），共装未实测。

日常使用

启动与入口

CLI 在目标仓库根目录调用；无常驻服务。

常用操作

操作一：把仓库打包成单文件

repomix . --compress --output repomix-output.txt

预期输出: Pack Summary（Total Files / Total Tokens / Output 路径；2026-08-29 实测 2 文件 → 1983 字符）

操作二：控制打包范围与 token 预算

repomix . --compress --include "src/**/*.ts,README.md"

预期输出: 只打包匹配的文件（--compress 实测通过；--include 为官方功能，未实测）

操作三：指定输出路径

repomix . --output /tmp/repo-context.txt

预期输出: 单文件写入指定路径（2026-08-29 实测 --output 生效）

数据与目录

• 输出：当前目录 repomix-output.txt（或 --output 指定路径）；
• 配置：可选 repomix.config.json（--init 生成，位于工作区，--init 写面未实测）。

卸载与清理

note: npm 全局卸载 + 命令面验证；残留项 = 输出文件与可选 repomix.config.json（工作区，手动删）

npm uninstall -g repomix
command -v repomix >/dev/null 2>&1 && echo "残留: repomix 仍存在" || echo "repomix removed: OK"

预期输出: repomix removed: OK

手动确认清单（如需彻底清理）：

• 输出文件（默认当前目录 repomix-output.txt，或 --output 指定路径）
• repomix.config.json（若曾用 --init 生成，位于工作区）
• ~/.npm 下 npx 缓存（npx 免安装形态使用，无需清理）

依赖警告

• 版本：[1.18.0, 1.18.0] 锁定（2026-08-29 实测版本）。
• 环境：Node >= 18（npm/npx 形态）；单二进制 Release 免 Node（未实测）。
• 网络：npm 用 npmmirror 前缀（2026-08-29 实测秒装）。
• 写面：不写用户级配置；输出单文件写当前目录（默认 repomix-output.txt，建议 .gitignore）。
• 共装：与 code-review-graph / swe-rex 判定 possible-compatible——写面不重叠（输出文件 / 审查报告 / 修复 diff），共装未实测。

FAQ（常见问题）

• 问：会改我的配置吗？答：不写用户级配置；运行时会读 ~/.config/repomix/ 下的可选全局配置（--init 写面未实测）；输出单文件写当前目录（默认 repomix-output.txt）。
• 问：和 code-review-graph / swe-rex 一起装会冲突吗？答：判定 possible-compatible——写面不重叠（输出文件 / 审查报告 / 修复 diff），共装未实测。
• 问：大仓库 token 超限怎么办？答：--compress 压缩 + --include 限定范围（2026-08-29 实测 站内文档 全目录 → 62KB/959 行单文件）。
• 问：输出文件会进 git 吗？答：默认排除 .gitignore 匹配项，但输出文件本身建议加入 .gitignore。
• 问：国内 npm 装不上？答：用安装段的 npmmirror 前缀（2026-08-29 实测秒装）。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。