Repomix（前身 Repopack）是一个把整个 Git 仓库打包成单个 AI 友好文件的命令行工具。截至本文写作时，它在 GitHub 上收获约 2.9 万 Star，main 分支几乎每天都有提交。你在项目根目录敲一条命令，它会把所有源码文件、目录结构、甚至 git 历史，整理成一个 XML / Markdown 文件，直接喂给 Claude、ChatGPT、DeepSeek、Gemini 这些大模型。
为什么需要它？大模型的上下文窗口再大，也装不下一个真实项目的几十个文件；手动一个一个复制粘贴既慢又漏。Repomix 自动读 .gitignore、排除敏感文件（内置 Secretlint 检测密钥）、用 Tree-sitter 压缩代码，最后输出一份让 AI 一眼看懂整个仓库的「项目说明书」。本文从零开始，把 Repomix 在你机器上装好、跑通第一个打包、接进你常用的 AI 工具。
一、项目介绍与适用场景
Repomix 是一个纯 CLI 工具，它的输入是一个仓库目录，输出是一个 repomix-output.xml 文件。适合：
- 给 AI 做代码评审：把整个仓库打包喂给 Claude，让它「先读一遍再提重构建议」。
- 跨项目熟悉代码：接手陌生仓库，先打包喂给 AI 让它给你讲一遍架构。
- AI 生成多文件代码：用 Claude Artifacts 这类功能，一次让 AI 输出多个相互关联的文件。
- CI 场景：在流水线里把仓库打包成上下文，喂给 AI 做自动 code review。
二、核心功能逐条拆解
- 一条命令打包：在项目根目录敲
repomix，自动读.gitignore、.ignore、.repomixignore。 - Token 计数：输出里带每个文件和整个仓库的 token 数，方便你判断是否超上下文。
- Secretlint 安全检测：自动识别像 API Key、密码格式的文件，排除在输出之外。
- Tree-sitter 压缩：
--compress用 Tree-sitter 提取关键代码元素，大幅降 token 但保留结构。 - 远程仓库打包：
--remote yamadashy/repomix直接打 GitHub 上的仓库，不用 clone。 - stdin 管道：
find ... | repomix --stdin自己选文件列表。 - git 历史：
--include-logs把最近 N 条 commit 也打包进去。 - 多形态：CLI、网页版（repomix.com）、Chrome / Firefox 扩展、VSCode 社区扩展（Repomix Runner）。
- 输出格式：XML（默认）、Markdown、纯文本，由网站版或配置切换。
三、全套官方链接
| 类型 | 链接 |
|---|---|
| GitHub 仓库 | https://github.com/yamadashy/repomix |
| 官方网站 | https://repomix.com |
| npm 包 | https://www.npmjs.com/package/repomix |
| Docker 镜像 | ghcr.io/yamadashy/repomix |
四、硬件与环境前置要求
Repomix 是一个 Node.js CLI，资源占用极小：
- 操作系统：任意能跑 Node.js 的系统（macOS / Linux / Windows）。
- Node.js：Node 18+。用 npx 则本机不需要预装 Node（npx 会自动拉）。
- Docker（可选）：如果不想装 Node，直接用官方 Docker 镜像。
- 磁盘：输出文件通常几百 KB 到几 MB，取决于仓库大小。
五、多平台安装步骤
5.1 无需安装（npx 直接跑）
官方 README 原文：
npx repomix@latest
在项目根目录执行，npx 会临时下载 repomix 并立刻打包当前目录。这是最快的试玩方式。
5.2 全局安装（npm / yarn / bun）
npm install -g repomix
# 或
yarn global add repomix
# 或
bun add -g repomix
5.3 Homebrew（macOS / Linux）
brew install repomix
装完后任意目录敲 repomix 即可。
5.4 Docker（不想装 Node 的环境）
官方 README 原文：
docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix
逐段解释：-v .:/app 把当前目录挂到容器 /app；--rm 用完删容器；镜像名是 GitHub Container Registry 的 ghcr.io/yamadashy/repomix。
打包指定子目录：
docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix path/to/directory
打包远程仓库到 ./output 目录：
docker run -v ./output:/app -it --rm ghcr.io/yamadashy/repomix --remote https://github.com/yamadashy/repomix
六、配置文件全部参数解释
6.1 初始化配置
repomix --init
会在当前目录生成 repomix.config.json，你可以在这里自定义 include / exclude、输出格式、压缩开关。
6.2 常用 CLI 参数表（全部来自官方 README）
| 参数 | 作用 | 示例 |
|---|---|---|
| （无参数） | 打包当前目录 | repomix |
path/to/dir |
打包指定目录 | repomix ./src |
--include "src/**/*.ts,**/*.md" |
只打包匹配 glob 的文件 | repomix --include "src/**/*.ts" |
--ignore "**/*.log,tmp/" |
排除匹配的文件 | repomix --ignore "**/*.log" |
--remote yamadashy/repomix |
直接打包 GitHub 远程仓库 | repomix --remote yamadashy/repomix |
--remote-branch main |
指定远程分支 / tag / commit | --remote-branch 935b695 |
--stdin |
从 stdin 读文件列表 | git ls-files "*.ts" \| repomix --stdin |
--include-logs |
打包最近 50 条 commit | repomix --include-logs |
--include-logs-count 10 |
指定 commit 数 | repomix --include-logs --include-logs-count 10 |
--include-diffs |
同时打包 diff | repomix --include-logs --include-diffs |
--compress |
用 Tree-sitter 压缩代码 | repomix --compress |
--init |
生成 repomix.config.json | repomix --init |
6.3 自定义忽略文件
除了 .gitignore，你可以在项目根建 .repomixignore（语法同 .gitignore），专门告诉 Repomix 哪些文件不要打。
七、启动、后台与日常使用
7.1 启动
cd your-project
repomix
预期输出：终端打印打包进度，最后在当前目录生成 repomix-output.xml。终端里还会打印总 token 数、文件数。
7.2 输出文件位置
默认在当前目录生成 repomix-output.xml。Docker 版把输出落到你挂载的目录里（如上面 ./output:/app）。
7.3 修改输出位置
在 repomix.config.json 里改 output.filePath（官方配置项），或在命令行用官方支持的 output 参数。
八、功能实操教程
第 1 步：找一个你熟悉的开源项目，git clone 到本地，cd 进去。
第 2 步：敲 npx repomix@latest。等几秒钟，看终端输出：打了多少文件、多少 token、多大的 XML。
第 3 步：打开生成的 repomix-output.xml，你会看到里面是结构化的目录树 + 每个文件的源码。
第 4 步：把这个文件拖进 Claude / ChatGPT 的对话框，附一段官方推荐提示词：
This file contains all the files in the repository combined into one.
I want to refactor the code, so please review it first.
第 5 步：试试压缩版——repomix --compress。对比两个 XML 的 token 数，会明显看到 Tree-sitter 压掉了多少。
第 6 步：试远程打包——repomix --remote yamadashy/repomix。不用 clone，直接打 GitHub 上的仓库。
第 7 步：试 git 历史——repomix --include-logs --include-logs-count 10。让 AI 顺便看看最近 10 次提交在做什么。
第 8 步：试管道——git ls-files "*.ts" | repomix --stdin。只把 TS 文件打包，给 AI 做专项分析。
九、全套报错故障排查
报错 1： npx: command not found
原因分析：本机没装 Node。
解决方案：装 Node 18+（用 nvm 或官网安装包）；或直接用 Docker 版（见 5.4）。
报错 2： 输出的 XML 里有很多 node_modules。
原因分析：没读 .gitignore 或你的项目没 .gitignore。
解决方案：确保项目根有 .gitignore 包含 node_modules/；或加 --ignore "node_modules/"。
报错 3： Secretlint 报密钥警告，打包被中断。
原因分析：仓库里真的有像密钥的字符串（如误提交的 .env）。
解决方案：把敏感文件加进 .repomixignore，或先把它们从仓库里清掉。
报错 4： 远程打包 404。
原因分析：仓库名拼错或仓库是 private。
解决方案：确认 --remote 后面是 owner/repo 格式；private 仓库需要本地 clone 后走本地打包。
报错 5： token 数超出模型上下文。
原因分析：仓库太大。
解决方案：加 --compress 压代码；用 --include 只打相关目录；或换更大上下文的模型。
十、升级、回滚与卸载
升级：npm update -g repomix / brew upgrade repomix。
备份建议：配置文件 repomix.config.json 跟项目走，不需要单独备份。
卸载：npm uninstall -g repomix / brew uninstall repomix。
十一、商用许可与合规风险提示
Repomix 本身是开源工具，可自由使用、二次开发、商用。注意几点：
- 它会把你的代码打成一个文件——打包前确认这个文件里没有真的密钥、证书、内网地址。Secretlint 只是辅助，不是银弹。
- 打出来的文件要喂给云端 AI 时，代码会离开你的机器；敏感项目请走本地模型（Ollama + 本地 Repomix）。
- 远程
--remote打的是公开仓库，private 仓库不支持直接远程打，避免误用。
参考链接
- GitHub 仓库：https://github.com/yamadashy/repomix
- 官方网站：https://repomix.com
- npm 包：https://www.npmjs.com/package/repomix
- Docker 镜像：https://github.com/yamadashy/repomix/pkgs/container/repomix