Lib.rs

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

作为命令行工具、库和 GitHub Action 提供。

目录

• 安装
• 特性
• 命令行使用
• 库使用
• GitHub Action 使用
• Pre-commit 使用
• 为 lychee 贡献
• 调试和改进异步代码
• 故障排除和解决方案
• 用户
• 致谢
• 许可证

安装

Arch Linux

pacman -S lychee

macOS

brew install lychee

Docker

docker pull lycheeverse/lychee

NixOS

nix-env -iA nixos.lychee

FreeBSD

pkg install lychee

Scoop

scoop install lychee

Termux

pkg install lychee

Alpine Linux

 # available for Alpine Edge in testing repositories
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 支持 several 特性标志

• 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 输出						1
静态二进制						️
Markdown 文件
HTML 文件
文本文件
网站支持
分块编码
GZIP 压缩
基本认证
自定义用户代理
相对 URL
锚点/片段
跳过相对 URL
包含模式	️
排除模式
处理重定向
忽略不安全的 SSL
文件通配符
限制方案
自定义头部
摘要
HEAD 请求
彩色输出
过滤状态码
自定义超时
电子邮件链接
进度条
重试和退避
跳过私有域名
用作库
静默模式
配置文件
Cookie
递归
惊人的 lychee 标志

¹ 支持其他机器可读格式，如 CSV。

命令行使用

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

lychee .

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

# check links in specific local file(s):
lychee README.md
lychee test.html info.txt

# check links on a website:
lychee https://endler.dev

# check links in directory but block network requests
lychee --offline path/to/directory

# check links in a remote file:
lychee https://raw.githubusercontent.com/lycheeverse/lychee/master/README.md

# check links in local files via shell glob:
lychee ~/projects/*/README.md

# check links in local files (lychee supports advanced globbing and ~ expansion):
lychee "~/projects/big_project/**/README.*"

# ignore case when globbing and check result for each link:
lychee --glob-ignore-case --verbose "~/projects/**/[r]eadme.*"

# check links from epub file (requires atool: https://www.nongnu.org/atool)
acat -F zip {file.epub} "*.xhtml" "*.html" | lychee -

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

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 命令行选项。它也可以在配置文件中设置。 这里是一个示例配置文件。

令牌可以在您的 GitHub 账户设置页面 上生成。一个没有额外权限的个人访问令牌足以能够检查公共存储库链接。

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

命令行参数

有一份详尽的命令行参数列表，可以自定义行为。以下为完整列表。

A fast, async link checker

Finds broken URLs and mail addresses inside Markdown, HTML, `reStructuredText`, websites and more!

Usage: lychee [OPTIONS] <inputs>...

Arguments:
  <inputs>...
          The inputs (where to get links to check from). These can be: files (e.g. `README.md`), file globs (e.g. `"~/git/*/README.md"`), remote URLs (e.g. `https://example.com/README.md`) or standard input (`-`). NOTE: Use `--` to separate inputs from options that allow multiple arguments

Options:
  -c, --config <CONFIG_FILE>
          Configuration file to use
          
          [default: lychee.toml]

  -v, --verbose...
          Set verbosity level; more output per occurrence (e.g. `-v` or `-vv`)

  -q, --quiet...
          Less output per occurrence (e.g. `-q` or `-qq`)

  -n, --no-progress
          Do not show progress bar.
          This is recommended for non-interactive shells (e.g. for continuous integration)

      --cache
          Use request cache stored on disk at `.lycheecache`

      --max-cache-age <MAX_CACHE_AGE>
          Discard all cached requests older than this duration
          
          [default: 1d]

      --dump
          Don't perform any link checking. Instead, dump all the links extracted from inputs that would be checked

      --dump-inputs
          Don't perform any link extraction and checking. Instead, dump all input sources from which links would be collected

      --archive <ARCHIVE>
          Specify the use of a specific web archive. Can be used in combination with `--suggest`
          
          [possible values: wayback]

      --suggest
          Suggest link replacements for broken links, using a web archive. The web archive can be specified with `--archive`

  -m, --max-redirects <MAX_REDIRECTS>
          Maximum number of allowed redirects
          
          [default: 5]

      --max-retries <MAX_RETRIES>
          Maximum number of retries per request
          
          [default: 3]

      --max-concurrency <MAX_CONCURRENCY>
          Maximum number of concurrent network requests
          
          [default: 128]

  -T, --threads <THREADS>
          Number of threads to utilize. Defaults to number of cores available to the system

  -u, --user-agent <USER_AGENT>
          User agent
          
          [default: lychee/x.y.z]

  -i, --insecure
          Proceed for server connections considered insecure (invalid TLS)

  -s, --scheme <SCHEME>
          Only test links with the given schemes (e.g. https). Omit to check links with any other scheme. At the moment, we support http, https, file, and mailto

      --offline
          Only check local files and block network requests

      --include <INCLUDE>
          URLs to check (supports regex). Has preference over all excludes

      --exclude <EXCLUDE>
          Exclude URLs and mail addresses from checking (supports regex)

      --exclude-file <EXCLUDE_FILE>
          Deprecated; use `--exclude-path` instead

      --exclude-path <EXCLUDE_PATH>
          Exclude file path from getting checked

  -E, --exclude-all-private
          Exclude all private IPs from checking.
          Equivalent to `--exclude-private --exclude-link-local --exclude-loopback`

      --exclude-private
          Exclude private IP address ranges from checking

      --exclude-link-local
          Exclude link-local IP address range from checking

      --exclude-loopback
          Exclude loopback IP address range and localhost from checking

      --exclude-mail
          Exclude all mail addresses from checking (deprecated; excluded by default)

      --include-mail
          Also check email addresses

      --remap <REMAP>
          Remap URI matching pattern to different URI

      --header <HEADER>
          Custom request header

  -a, --accept <ACCEPT>
          A List of accepted status codes for valid links
          
          The following accept range syntax is supported: [start]..[=]end|code. Some valid
          examples are:
          
          - 200..=204
          - 200..204
          - ..=204
          - ..204
          - 200
          
          Use "lychee --accept '200..=204, 429, 500' <inputs>..." to provide a comma-
          separated list of accepted status codes. This example will accept 200, 201,
          202, 203, 204, 429, and 500 as valid status codes.
          
          [default: 100..=103,200..=299]

      --include-fragments
          Enable the checking of fragments in links

  -t, --timeout <TIMEOUT>
          Website timeout in seconds from connect to response finished
          
          [default: 20]

  -r, --retry-wait-time <RETRY_WAIT_TIME>
          Minimum wait time in seconds between retries of failed requests
          
          [default: 1]

  -X, --method <METHOD>
          Request method
          
          [default: get]

  -b, --base <BASE>
          Base URL or website root directory to check relative URLs e.g. https://example.com or `/path/to/public`

      --basic-auth <BASIC_AUTH>
          Basic authentication support. E.g. `http://example.com username:password`

      --github-token <GITHUB_TOKEN>
          GitHub API token to use when checking github.com links, to avoid rate limiting
          
          [env: GITHUB_TOKEN]

      --skip-missing
          Skip missing input files (default is to error if they don't exist)

      --include-verbatim
          Find links in verbatim sections like `pre`- and `code` blocks

      --glob-ignore-case
          Ignore case when expanding filesystem path glob inputs

  -o, --output <OUTPUT>
          Output file of status report

  -f, --format <FORMAT>
          Output format of final status report (compact, detailed, json, markdown)
          
          [default: compact]

      --require-https
          When HTTPS is available, treat HTTP links as errors

      --cookie-jar <COOKIE_JAR>
          Tell lychee to read cookies from the given file. Cookies will be stored in the cookie jar and sent with requests. New cookies will be stored in the cookie jar and existing cookies will be updated

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print 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: 0.15.1
    hooks:
      - id: lychee
        # Optionally include additional CLI arguments
        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 更快的方法，请与我们联系。

故障排除和解决方案

我们在我们的故障排除指南中收集了针对各种网站的一些常见解决方案。

用户

• https://github.com/InnerSourceCommons/InnerSourcePatterns
• https://github.com/opensearch-project/OpenSearch
• https://github.com/ramitsurana/awesome-kubernetes
• https://github.com/papers-we-love/papers-we-love
• https://github.com/pingcap/docs
• https://github.com/microsoft/WhatTheHack
• https://github.com/Azure/ResourceModules
• https://github.com/nix-community/awesome-nix
• https://github.com/balena-io/docs
• https://github.com/launchdarkly/LaunchDarkly-Docs
• https://github.com/pawroman/links
• https://github.com/analysis-tools-dev/static-analysis
• https://github.com/analysis-tools-dev/dynamic-analysis
• https://github.com/mre/idiomatic-rust
• https://github.com/bencherdev/bencher
• https://github.com/lycheeverse/lychee (是的，龙眼文档是用龙眼校对的 🤯)

如果您在项目中使用龙眼，请在此处添加。

致谢

龙眼的第一版原型是在Hello Rust第10集中构建的。感谢自开始以来一直支持我们发展的所有GitHub和Patreon赞助商。还要感谢所有为使此项目更加成熟做出贡献的杰出贡献者。

许可证

龙眼根据您的选择许可为以下之一

• Apache许可证，版本2.0，(LICENSE-APACHE或https://apache.ac.cn/licenses/LICENSE-2.0)
• MIT许可证 (LICENSE-MIT或https://opensource.org/licenses/MIT)

。