在安装了 Cursor CLI 后，执行 agent 命令启动它时，却报了如下错误：

Could not find ripgrep (rg) binary. Please install ripgrep. Error: rg is not installed

这说明 ripgrep 是其必备的依赖。从名称可以猜测其是一个类似 grep 文本搜索工具。安装它后，再执行 agent 命令，就能正常启动了。

但这也引起了我的好奇：ripgrep 是什么工具？它和 grep 有什么区别？ 在一番调研总结之后，便有了本文内容。

下文是一篇面向新手的 ripgrep 入门技术文章：从“它是什么”，到“如何安装与上手”，再到“高级用法和真实场景案例”，帮你在 30 分钟内把这把搜索“瑞士军刀”装进你的日常工作流。

---

一、ripgrep 是什么？

ripgrep 是一个用 Rust 编写的命令行全文搜索工具，它在真实项目里的搜索速度往往是传统 grep 的数倍甚至数十倍，同时拥有更聪明的默认行为——比如自动遵守 .gitignore、跳过二进制和无关目录，让搜索结果干净、聚焦。其最新的大版本系列是 15.x，最新发布版本为 15.1.0（2025-10-22），仍在积极维护更新。

一句话简介：

ripgrep（命令名 rg）是一个“按行搜索”的命令行工具，它会递归遍历目录，用正则表达式在文件中搜索内容，默认遵守 .gitignore 规则，性能极快，跨平台可用。

稍微展开一点：

• 搜索粒度：面向“行”（line-oriented），即把文件一行一行读入并匹配。
• 搜索范围：递归当前目录及子目录中的文件。
• 过滤行为（默认）：
  • 尊重 .gitignore / .ignore / .rgignore
  • 自动跳过隐藏文件/目录（如 .git/）
  • 自动跳过二进制文件
• 跨平台：Windows、macOS、Linux 全平台提供一流支持和官方二进制包。
• 在很多场景下，它可以直接替代：
  • grep
  • ack
  • The Silver Searcher (ag)
  • git grep 等

如果你习惯在终端用 grep 搜索项目，那么几乎可以“原地”换成 rg，获得更快更聪明的体验。

---

二、核心特性总览（和 grep 相比到底好在哪）

1. 性能：在大项目中远超 grep

在 How-To Geek 的一次对比测试中，在大约 40,000 个文件的目录下搜索同一个模式：

• grep：约 30 秒
• ripgrep：约 0.6 秒（不到 1 秒）

也就是说，在类似场景里，ripgrep 的实际体验可以达到 几十倍的提速，并且官方和社区多次测试都表明：

在现代代码仓库中，ripgrep 通常是 grep、ack、ag 等工具中综合表现最好的一个。

性能优势来自多方面：

• 使用 Rust 高性能正则引擎和 有限状态机 + SIMD 向量化 优化
• 多线程并行地扫描文件
• 默认遵守 .gitignore 并跳过二进制/隐藏文件，减少无效 I/O

2. 默认行为非常“懂开发者”

与 grep 相比，ripgrep 的默认行为更贴近现代开发场景：

• 默认自动：
  • 遵守 .gitignore / .ignore / .rgignore
  • 忽略隐藏目录（如 .git/、.svn/）
  • 忽略二进制文件
• 想要“什么都别忽略”，只需添加 -uuu 参数：
  bash
rg -uuu PATTERN

你不用再自己维护一堆排除规则，默认结果就是更干净、更聚焦于“代码和文本”。

3. 丰富的功能集

ripgrep 内置了大量实用能力，常用的包括：

• 文件类型过滤
  • -t TYPE：只搜索某类文件（如 -tpy 搜索 Python）
  • -T TYPE：排除某类文件（如 -Tjs 排除 JS）
  • --type-list：列出所有支持的类型
  • --type-add：在配置文件中增加自定义类型
• 高级正则支持
  • 默认使用 Rust regex 引擎（高性能，支持大部分常见语法）
  • 可用 -P / --pcre2 开启 PCRE2 引擎，支持 lookaround 等高级特性
  • 可借 --engine default|pcre2|auto 控制选择
• 多模式、多文件搜索
  • -e PATTERN 可多次指定实现“或”条件
  • 可一次匹配多个目录或文件
• 编码与压缩支持
  • -E / --encoding：指定编码（UTF-8、UTF-16、GBK 等）
  • -z / --search-zip：搜索压缩文件（gzip、xz、zstd、bzip2 等）
• 输出与替换
  • 行号、上下文显示（类似 grep -n -C）
  • 彩色高亮，支持复杂的颜色样式配置
  • 简单的替换输出（-r / --replace）
  • JSON 输出模式（便于被其他工具消费）

---

三、安装方法：主流平台一网打尽

3.1 macOS

最推荐用 Homebrew：

brew install ripgrep

如果你使用 MacPorts：

sudo port install ripgrep

安装后，终端执行：

rg --version

能看到版本号说明安装成功。

3.2 Windows

多种包管理器可选：

# Chocolatey
choco install ripgrep

# Scoop
scoop install ripgrep

# Winget（官方 MSVC 版本）
winget install BurntSushi.ripgrep.MSVC

安装好后，在 PowerShell / CMD / Git Bash 中执行：

rg --version

3.3 Linux 发行版

绝大部分主流发行版都有官方包：

# Debian / Ubuntu
sudo apt-get install ripgrep

# Fedora
sudo dnf install ripgrep

# Arch Linux
sudo pacman -S ripgrep

# openSUSE
sudo zypper install ripgrep

# FreeBSD
sudo pkg install ripgrep

# OpenBSD
doas pkg_add ripgrep

其他如 Void、NixOS 等也都有对应包，可见各自文档。

3.4 用 Rust 自己编译（面向开发者）

你也可以直接从源代码构建：

# 要求 Rust 1.85.0+（stable）
git clone https://github.com/BurntSushi/ripgrep
cd ripgrep
cargo build --release

./target/release/rg --version

如果需要 PCRE2 支持：

cargo build --release --features 'pcre2'

这样可以在构建时控制平台、静态链接等高级选项。

---

四、基础使用：从 “grep” 到 “rg” 的无痛迁移

ripgrep 的基本语法：

rg [选项] PATTERN [PATH...]

• PATTERN：要搜索的字符串或正则表达式
• PATH：一个或多个文件/目录，不填时默认是当前目录

4.1 最常用的几条命令

# 在当前目录递归搜索 "error"
rg "error"

# 大小写不敏感
rg -i "error"

# 显示行号
rg -n "error"

# 只列出包含匹配的文件名
rg -l "error"

# 显示每个文件中匹配的次数
rg -c "error"

和 grep 的映射大致可以理解为：

• grep -R PATTERN ≈ rg PATTERN
• grep -Rni PATTERN ≈ rg -ni PATTERN

4.2 控制搜索范围与类型

只看某些后缀（类型）

# 只在 .txt 文件中搜索
rg -t txt "TODO"

# 只在 Python 源码中搜索
rg -t py "def main"

# 列出当前支持的所有类型
rg --type-list

排除某类文件

# 排除 Markdown 文件
rg -T md "config"

# 排除 JavaScript 文件
rg -T js "foo"

取消所有忽略规则

有时你真的想“全盘扫描”，不管 .gitignore、隐藏目录还是二进制：

rg -uuu "secret"

-u、-uu、-uuu 分别逐步放宽过滤，最常用的一般是直接上 -uuu。

4.3 精确匹配和多模式搜索

整词匹配

# 只匹配整个单词 error，不匹配 error_code
rg -w "error"

多个模式“或”匹配

# 匹配 error 或 warning
rg -e "error" -e "warning"

使用高级正则（PCRE2）

当你需要 lookahead / lookbehind 等高级正则特性时：

rg -P "(?<=ERROR )\d{3}"   # 匹配 ERROR 后面的 3 位数字

---

五、特色功能与典型用法案例

这一部分更偏“实战”：展示一些在真实项目中极其常见、又非常适合用 ripgrep 解决的问题。

5.1 案例 1：在大代码库里做“全局代码审查”

目标：找出所有“潜在不安全代码”，比如 Rust 代码里 unsafe {} 的使用位置。

# 在 src 目录中查找包含 unsafe 块的行
rg -n "unsafe\s*\{" src

如果想更严格一点，用 PCRE2 勾勒匹配范围：

rg -nP 'unsafe\s*\{[^\}]*\}' src/

可以快速扫出所有使用 unsafe 的地方，进一步人工审查。

5.2 案例 2：生产日志排障（含 IP 匹配）

场景：排查一台后端服务，想找“某个 IP 对应的错误请求”。

# 在 /var/log/app 中，搜索含 IP 且带 error 的行
rg -nP '\d{1,3}(\.\d{1,3}){3}.*error' /var/log/app/

搭配 -i、-C 等选项效果更佳：

# 忽略大小写，显示上下文各 3 行
rg -niP '\d{1,3}(\.\d{1,3}){3}.*error' /var/log/app/ -C 3

5.3 案例 3：为代码重构做“全局引用分析”

目标：重命名某个函数，想先找出所有调用点。

以 C++ 为例，查找 exampleFunction(...) 的调用：

rg -n '\bexampleFunction\s*\(' ./src

解释：

• \b：单词边界，防止匹配到 my_exampleFunction
• \s*：允许函数名与左括号之间有空格

如果这次重构只想关注 .cpp / .h 文件：

rg -n -t cpp -t c '\bexampleFunction\s*\(' src/

5.4 案例 4：快速调查“某个配置项在哪些环境启用”

假设你有大量 YAML / JSON 配置文件，需要查某个开关项：

# 所有 yaml 配置中，搜索 feature_x_enabled
rg -n -t yaml "feature_x_enabled" config/

配合 --stats 看搜索范围和匹配概况：

rg -n --stats "feature_x_enabled" config/

5.5 案例 5：压缩日志直接搜索（不必提前解压）

运维常见场景：应用日志被轮转成 .log.gz，不想先手动 zcat。

# 在所有 .log.gz 里搜 error
rg -zn "error" *.log.gz

-z 会让 ripgrep 识别并解包多种压缩格式（gzip、zstd、xz、bzip2 等）。

5.6 案例 6：多编码文本搜索（如 UTF-16 日志）

一些 Windows 系统一直在产出 UTF-16 编码日志，此时需要显式指定编码：

rg -nE UTF-16 "登录失败" C:\logs\app.log

其中 -E / --encoding 参数标明文件编码，ripgrep 会负责解码后再做匹配。

---

六、与编辑器 / IDE 的联动：把 rg 融进日常开发

ripgrep 目前已经成为许多“模糊搜索 / 全局搜索插件”的事实标准后端。

6.1 Neovim / Vim

常见做法之一是安装如 vim-ripgrep 的插件，并绑定快捷键：

" 在 vim 或 neovim 的配置中：
nnoremap <leader>rg :Rg<space>

这样在普通模式下按 <leader>rg（一般是 \rg 或 ,rg 看你配置），输入关键字即可在 quickfix 窗口中查看结果并一键跳转。

很多现代 Neovim 配置（如 Telescope、fzf.vim、Leaderf 等）也可将 rg 设为后端，实现“模糊文件 + 内容搜索”的 IDE 式体验。

6.2 VS Code

VS Code 内置搜索就是基于 ripgrep 实现的，无需额外配置即可享受 rg 的性能。

若你要在某些高级配置或扩展中明确声明使用 ripgrep，大致也会是类似：

{
  "search.useRipgrep": true
}

6.3 Emacs

可以使用 rg.el 等扩展，在 Emacs 内直接调用 ripgrep：

(require 'rg)
(rg-project "TODO")    ;; 在当前项目中搜索 TODO

搜索结果会展示在专门的 buffer 内，并支持跳转、过滤等操作。

---

七、配置与定制：用 .ripgreprc 打造自己的默认行为

ripgrep 支持通过配置文件自定义默认选项。默认配置文件位置一般是：

• Linux/macOS：~/.ripgreprc
• Windows：%USERPROFILE%\.ripgreprc（具体可查手册）

你可以把常用选项写进去，例如：

# ~/.ripgreprc 示例

# 始终启用彩色输出
--color=always

# 默认大小写不敏感
--ignore-case

# 自定义一个“web”类型：HTML/CSS/JS/JSX
--type-add=web:*.{html,css,js,jsx}

# 默认排除 node_modules
--ignore=node_modules

# 为输出着色风格增加 italic 等
--colors=match:fg:yellow
--colors=match:style:bold

之后无论在哪个项目，只要运行 rg pattern，这些行为都会自动生效。

---

八、总结与实践建议（给刚上手的你）

如果你刚刚听说 ripgrep，或者已经安装但还没形成肌肉记忆，可以试着按照下面几个步骤来“迁移你的 grep 习惯”：

1. 先把 grep 换成 rg
   把你日常 grep -R "xxx" 的习惯，直接替换成：

   rg "xxx"
   

   你会立刻感到：

   • 搜索变快了
   • 结果更干净（少了各种构建产物和 .git 垃圾）
2. 掌握 5 个高频参数：-n、-i、-w、-t、-T
   • -n：显示行号
   • -i：忽略大小写
   • -w：整词匹配
   • -t：只搜索某类文件
   • -T：排除某类文件
3. 在自己的编辑器里启用 ripgrep
   • Neovim/Vim：装一个基于 rg 的模糊搜索插件，绑个快捷键
   • VS Code：知道它已经在后台帮你用了 rg（理解其强大）
   • Emacs：装好 rg.el，感受一下项目级的顺滑搜索体验
4. 创建一个最小 .ripgreprc
   把你最常用的设置写进去，比如统一忽略 node_modules、开启彩色输出等，之后所有项目都能自动受益。

当你养成这些习惯之后，你会逐渐发现：
无论是快速搜索“这个函数到底被谁调用过？”，还是在海量日志中定位一个请求 ID，抑或做批量重构前的全局检查——rg 都会变成你下意识使用的第一工具。

---

ripgrep 仓库地址：
- GitHub: https://github.com/BurntSushi/ripgrep

如果你现在终端里还只有 grep，不妨先执行下面两行，开启一个全新的搜索时代：

# 安装（以 macOS Homebrew 为例）
brew install ripgrep

# 体验第一下
rg "TODO" .