lychee

<a name="back-to-top"></a> lychee

Rust

⚡ 一个用Rust编写的快速、异步、基于流的链接检查器。可以在Markdown、HTML、reStructuredText或任何其他文本文件或网站中查找损坏的超链接和邮件地址！

可作为命令行工具、库和GitHub Action使用。

Lychee 演示

安装

Arch Linux

pacman -S lychee

OpenSUSE Tumbleweed

zypper in lychee

macOS

brew install lychee

Docker

docker pull lycheeverse/lychee

NixOS

nix-env -iA nixos.lychee

Nixpkgs

用于配置、Nix shells等的lychee包
让Nix使用
testers.lycheeLinkCheck { site = …; }检查打包的站点

FreeBSD

pkg install lychee

Scoop

scoop install lychee

Termux

pkg install lychee

Alpine Linux

 # 在测试仓库中可用于Alpine Edge
apk add lychee

预编译二进制文件

我们为每个版本提供Linux、macOS和Windows的二进制文件。
你可以从发布页面下载它们。

Cargo

构建依赖

在基于APT/dpkg的Linux发行版（如Debian、Ubuntu、Linux Mint和Kali Linux）上，以下命令将安装所有必需的构建依赖，包括Rust工具链和cargo：

curl -sSf 'https://sh.rustup.rs' | sh
apt install gcc pkg-config libc6-dev libssl-dev

编译和安装lychee

cargo install lychee

特性标志

Lychee支持几个特性标志：

native-tls启用平台原生TLS crate native-tls。
vendored-openssl编译并静态链接OpenSSL的副本。参见openssl crate的相应特性。
rustls-tls启用替代TLS crate rustls。
email-check使用check-if-email-exists crate启用电子邮件地址检查。此特性需要native-tls特性。
check_example_domains允许检查示例域名，如example.com。此特性对测试很有用。

默认情况下，启用native-tls和email-check。

特性

这个比较是基于尽最大努力进行的。如果有过时的信息，请创建PR以修复。

	lychee	awesome_bot	muffet	broken-link-checker	linkinator	linkchecker	markdown-link-check	fink
语言	Rust	Ruby	Go	JS	TypeScript	Python	JS	PHP
异步/并行
JSON输出						<sup>1</sup>
静态二进制						️
Markdown文件
HTML文件
文本文件
网站支持
分块编码
GZIP压缩
基本认证
自定义用户代理
相对URL
锚点/片段
跳过相对URL
包含模式	️
排除模式
处理重定向
忽略不安全的SSL
文件通配
限制协议
自定义头部
摘要
`HEAD`请求
彩色输出
过滤状态码
自定义超时
电子邮件链接
进度条
重试和退避
跳过私有域名
用作库
安静模式
配置文件
Cookie
递归
酷炫的lychee标志

<sup>1</sup> 支持其他机器可读格式，如CSV。

命令行使用

递归检查当前目录下支持的文件中的所有链接

lychee .

您还可以指定各种类型的输入：

# 检查特定本地文件中的链接：
lychee README.md
lychee test.html info.txt

# 检查网站上的链接：
lychee https://endler.dev

# 检查目录中的链接但阻止网络请求
lychee --offline path/to/directory

# 检查远程文件中的链接：
lychee https://raw.githubusercontent.com/lycheeverse/lychee/master/README.md

# 使用shell通配符检查本地文件中的链接：
lychee ~/projects/*/README.md

# 检查本地文件中的链接（lychee支持高级通配和~展开）：
lychee "~/projects/big_project/**/README.*"

# 通配时忽略大小写并检查每个链接的结果：
lychee --glob-ignore-case --verbose "~/projects/**/[r]eadme.*"
# 检查 epub 文件中的链接（需要 atool：https://www.nongnu.org/atool）
acat -F zip {file.epub} "*.xhtml" "*.html" | lychee -

lychee 会将其他文件格式解析为纯文本，并使用 linkify 提取链接。如果没有特定的格式或编码要求，这通常效果很好，但如果您需要专门支持新的文件格式，请考虑创建一个 issue。

Docker 使用

以下是如何将本地目录挂载到容器中并使用 lychee 检查一些输入的方法。

传递 --init 参数，以便可以从终端停止 lychee。
我们还传递 -it 以启动交互式终端，这是显示进度条所必需的。
--rm 在运行后从主机上移除不再使用的容器（自我清理）。
-w /input 将 /input 指定为默认工作空间。
-v $(pwd):/input 将本地卷挂载到容器中，以供 lychee 访问。

默认情况下使用基于 Debian 的 Docker 镜像。如果您想运行基于 Alpine 的镜像，请使用 latest-alpine 标签。例如，lycheeverse/lychee:latest-alpine

Linux/macOS shell 命令

docker run --init -it --rm -w /input -v $(pwd):/input lycheeverse/lychee README.md

Windows PowerShell 命令

docker run --init -it --rm -w /input -v ${PWD}:/input lycheeverse/lychee README.md

GitHub 令牌

为避免在检查 GitHub 链接时受到速率限制，您可以选择设置一个包含 GitHub 令牌的环境变量，如 GITHUB_TOKEN=xxxx，或使用 --github-token CLI 选项。它也可以在配置文件中设置。 [这里是一个示例配置文件][config file]。

可以在您的 GitHub 账户设置页面生成令牌。无需额外权限的个人访问令牌足以检查公共仓库链接。

对于更具可扩展性的组织范围场景，您可以考虑使用 GitHub App。它比个人访问令牌具有更高的速率限制，但需要在 GitHub 工作流程中进行额外的配置步骤。请参照 GitHub App 设置示例。

命令行参数

有大量的命令行参数可以自定义行为。下面是完整列表。

一个快速、异步的链接检查器

在 Markdown、HTML、`reStructuredText`、网站和更多内容中查找损坏的 URL 和邮件地址！

用法：lychee [选项] <输入>...

参数：
  <输入>...
          输入（从何处获取要检查的链接）。这些可以是：文件（如 `README.md`）、文件通配符（如 `"~/git/*/README.md"`）、远程 URL（如 `https://example.com/README.md`）或标准输入（`-`）。注意：使用 `--` 分隔输入和允许多个参数的选项

选项：
  -c, --config <配置文件>
          要使用的配置文件
          
          [默认：lychee.toml]

  -v, --verbose...
          设置详细程度级别；每次出现增加输出（例如 `-v` 或 `-vv`）

  -q, --quiet...
          每次出现减少输出（例如 `-q` 或 `-qq`）

  -n, --no-progress
          不显示进度条。
          建议在非交互式 shell 中使用（例如持续集成）

      --cache
          使用存储在磁盘上 `.lycheecache` 的请求缓存

      --max-cache-age <最大缓存时间>
          丢弃所有早于此持续时间的缓存请求
          
          [默认：1d]

      --dump
          不执行任何链接检查。相反，转储所有从输入中提取的将被检查的链接

      --dump-inputs
          不执行任何链接提取和检查。相反，转储所有将收集链接的输入源

      --archive <归档>
          指定使用特定的网络归档。可与 `--suggest` 结合使用
          
          [可能的值：wayback]

      --suggest
          为损坏的链接建议替换链接，使用网络归档。可以使用 `--archive` 指定网络归档

  -m, --max-redirects <最大重定向次数>
          允许的最大重定向次数
          
          [默认：5]

      --max-retries <最大重试次数>
          每个请求的最大重试次数
          
          [默认：3]

      --max-concurrency <最大并发数>
          最大并发网络请求数
          
          [默认：128]

  -T, --threads <线程数>
          要使用的线程数。默认为系统可用的核心数

  -u, --user-agent <用户代理>
          用户代理
          
          [默认：lychee/x.y.z]

  -i, --insecure
          对被认为不安全的服务器连接继续进行（无效的 TLS）

  -s, --scheme <方案>
          仅测试具有给定方案的链接（例如 https）。省略以检查具有任何其他方案的链接。目前，我们支持 http、https、file 和 mailto

      --offline
          仅检查本地文件并阻止网络请求

      --include <包含>
          要检查的 URL（支持正则表达式）。优先于所有排除项

      --exclude <排除>
          从检查中排除 URL 和邮件地址（支持正则表达式）

      --exclude-file <排除文件>
          已弃用；请改用 `--exclude-path`

      --exclude-path <排除路径>
          从检查中排除文件路径

  -E, --exclude-all-private
          从检查中排除所有私有 IP。
          等同于 `--exclude-private --exclude-link-local --exclude-loopback`

      --exclude-private
          从检查中排除私有 IP 地址范围

      --exclude-link-local
          从检查中排除链路本地 IP 地址范围

      --exclude-loopback
          从检查中排除环回 IP 地址范围和 localhost

      --exclude-mail
          从检查中排除所有邮件地址（已弃用；默认排除）

      --include-mail
          也检查电子邮件地址

      --remap <重映射>
          将匹配模式的 URI 重映射到不同的 URI

      --fallback-extensions <后备扩展名>
          在本地检查文件时，为 URI 测试指定的文件扩展名。
          多个扩展名可以用逗号分隔。扩展名将按出现顺序检查。
          
          示例：--fallback-extensions html,htm,php,asp,aspx,jsp,cgi

      --header <头部>
          自定义请求头部

  -a, --accept <接受>
          有效链接的接受状态码列表
          
          支持以下接受范围语法：[开始]..[=]结束|代码。一些有效示例是：
          
          - 200..=204
          - 200..204
          - ..=204
          - ..204
          - 200
          
          使用 "lychee --accept '200..=204, 429, 500' <输入>..." 提供逗号分隔的接受状态码列表。这个例子将接受 200、201、202、203、204、429 和 500 作为有效状态码。
          
          [默认：100..=103,200..=299]

      --include-fragments
          启用链接中片段的检查

  -t, --timeout <超时>
          从连接到响应完成的网站超时时间（秒）
          
          [默认：20]

  -r, --retry-wait-time <重试等待时间>
          失败请求重试之间的最小等待时间（秒）
          
          [默认：1]

  -X, --method <方法>
          请求方法
          
          [默认：get]

  -b, --base <基础>
          检查相对 URL 的基础 URL 或网站根目录，例如 <https://example.com> 或 `/path/to/public`

      --basic-auth <基本认证>
          基本认证支持。例如 `http://example.com username:password`

      --github-token <GITHUB令牌>
          检查 github.com 链接时使用的 GitHub API 令牌，以避免速率限制
          
          [环境变量：GITHUB_TOKEN]

      --skip-missing
          跳过缺失的输入文件（默认是在它们不存在时报错）

      --include-verbatim
          在原文区域（如 `pre` 和 `code` 块）中查找链接

      --glob-ignore-case
          展开文件系统路径通配符输入时忽略大小写

  -o, --output <输出>
          状态报告的输出文件

      --mode <模式>
          设置输出显示模式。决定结果在终端中的呈现方式
          
          [默认：color]
          [可能的值：plain, color, emoji]

  -f, --format <格式>
          最终状态报告的输出格式
          
          [默认：compact]
          [可能的值：compact, detailed, json, markdown, raw]

      --require-https
          当 HTTPS 可用时，将 HTTP 链接视为错误

      --cookie-jar <cookie jar>
          告诉 lychee 从给定文件读取 cookie。Cookie 将存储在 cookie jar 中并随请求发送。新的 cookie 将存储在 cookie jar 中，现有的 cookie 将被更新

  -h, --help
          打印帮助信息（使用 '-h' 查看摘要）

  -V, --version
          打印版本

退出代码

0 表示成功（所有链接都成功检查或按配置排除/跳过）
1 表示缺少输入和任何意外的运行时故障或配置错误
2 表示链接检查失败（如果任何非排除链接检查失败）
3 表示配置文件中的错误

忽略链接

您可以通过指定正则表达式模式来排除链接被检查,例如使用 --exclude (如 --exclude example\.(com|org))。如果当前工作目录中存在名为 .lycheeignore 的文件,其内容也会被排除。该文件允许您列出多个用于排除的正则表达式(每行一个模式)。

要排除扫描特定文件/目录,请使用 lychee.toml 和 exclude_path。

exclude_path = ["some/path", "*/dev/*"]

缓存

如果设置了 --cache 标志,lychee 将在当前目录下的 .lycheecache 文件中缓存响应。如果该文件存在且设置了该标志,则缓存将在启动时加载。这可以大大加快未来的运行速度。请注意,默认情况下 lychee 不会在磁盘上存储任何数据。

库使用

您可以将 lychee 作为库用于自己的项目! 以下是一个"hello world"示例:

use lychee_lib::Result;

#[tokio::main]
async fn main() -> Result<()> {
  let response = lychee_lib::check("https://github.com/lycheeverse/lychee").await?;
  println!("{response}");
  Ok(())
}

这等同于以下代码片段,我们在其中构建了自己的客户端:

use lychee_lib::{ClientBuilder, Result, Status};

#[tokio::main]
async fn main() -> Result<()> {
  let client = ClientBuilder::default().client()?;
  let response = client.check("https://github.com/lycheeverse/lychee").await?;
  assert!(response.status().is_success());
  Ok(())
}

客户端构建器非常可定制:

let client = lychee_lib::ClientBuilder::builder()
    .includes(includes)
    .excludes(excludes)
    .max_redirects(cfg.max_redirects)
    .user_agent(cfg.user_agent)
    .allow_insecure(cfg.insecure)
    .custom_headers(headers)
    .method(method)
    .timeout(timeout)
    .github_token(cfg.github_token)
    .scheme(cfg.scheme)
    .accepted(accepted)
    .build()
    .client()?;

您设置的所有选项将用于所有链接检查。有关所有选项,请参阅构建器文档。更多信息请查看示例文件夹。

GitHub Action 使用

使用 lychee 的 GitHub Action 作为单独的仓库提供:lycheeverse/lychee-action, 其中包含使用说明。

Pre-commit 使用

Lychee 也可以作为 pre-commit 钩子使用。

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/lycheeverse/lychee.git
    rev: v0.15.1
    hooks:
      - id: lychee
        # 可选择包含其他 CLI 参数
        args: ["--no-progress", "--exclude", "file://"]

Lychee 可以针对整个仓库运行,而不仅仅是暂存文件。

- id: lychee
  args: ["--no-progress", "."]
  pass_filenames: false

为 lychee 做贡献

我们感谢任何贡献。我们尽量保持问题跟踪器的最新状态,以便您可以快速找到要处理的任务。

尝试以下链接开始:

有关更详细的说明,请查看 CONTRIBUTING.md。

调试和改进异步代码

Lychee 大量使用异步代码,以在保持性能的同时节省资源。然而,用大多数工具调试异步代码可能很困难。因此,我们提供了对 tokio-console 的实验性支持。它为异步任务提供了类似 top(1) 的概览!

如果您想尝试一下,请下载并启动控制台:

git clone https://github.com/tokio-rs/console
cd console
cargo run

然后使用一些特殊标志和启用的功能运行 lychee。

RUSTFLAGS="--cfg tokio_unstable" cargo run --features tokio-console -- <input1> <input2> ...

如果您找到让 lychee 更快的方法,请与我们联系。

故障排除和解决方法

我们在故障排除指南中收集了各种网站的常见解决方法列表。

用户

如果您正在为您的项目使用 lychee,请将其添加到此处。

致谢

lychee 的第一个原型是在 Hello Rust 的第 10 集中构建的。感谢所有 GitHub 和 Patreon 赞助商从一开始就支持开发。另外,感谢所有优秀的贡献者,他们让这个项目变得更加成熟。

许可证

lychee 采用以下两种许可证之一:

Apache License, Version 2.0, (LICENSE-APACHE 或 https://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT 或 https://opensource.org/licenses/MIT)

由您选择。

<br><hr> 🔼 返回顶部

目录

安装

Arch Linux

OpenSUSE Tumbleweed

macOS

Docker

NixOS

Nixpkgs

FreeBSD

Scoop

Termux

Alpine Linux

预编译二进制文件

Cargo

构建依赖

编译和安装lychee

特性标志

特性

命令行使用

Docker 使用

Linux/macOS shell 命令

Windows PowerShell 命令

GitHub 令牌

命令行参数

退出代码

忽略链接

缓存

库使用

GitHub Action 使用

Pre-commit 使用

为 lychee 做贡献

调试和改进异步代码

故障排除和解决方法

用户

致谢

许可证

编辑推荐精选

Trae

问小白

Transly

讯飞智文

讯飞星火

Spark-TTS

咔片PPT

讯飞绘文

材料星

openai-agents-python

探索AI的无限可能

推荐工具精选

Trae

豆包

讯飞文书

讯飞绘文

讯飞绘镜

阿里绘蛙

咔片PPT

AI云服务特惠

火山引擎

阿里云

腾讯云

华为云

百度智能云

AWS

关注微信公众号