Lib.rs

› Web 编程 | 命令行工具
#markdown-html #link #checker #github-action #validation #link-checker #progress-bar

app lychee

快速、异步链接检查器

由 Matthias Endler 和 56 位贡献者 编写

27 个版本 (14 个重大更改)

0.15.1 2024年4月29日
0.14.3 2024年2月5日
0.13.0 2023年5月14日
0.11.1 2023年2月22日
0.3.0 2020年8月18日

#44 in Web 编程

Download history 348/week @ 2024-05-02 310/week @ 2024-05-09 363/week @ 2024-05-16 354/week @ 2024-05-23 313/week @ 2024-05-30 377/week @ 2024-06-06 349/week @ 2024-06-13 442/week @ 2024-06-20 296/week @ 2024-06-27 319/week @ 2024-07-04 324/week @ 2024-07-11 307/week @ 2024-07-18 323/week @ 2024-07-25 387/week @ 2024-08-01 369/week @ 2024-08-08 471/week @ 2024-08-15

1,597 每月下载量

Apache-2.0 OR MIT 和可能 AGPL-3.0

455KB
8K SLoC

lychee

Homepage GitHub Marketplace Rust docs.rs Check Links Docker Pulls

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

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

Lychee demo

目录

安装

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 支持多个特性标志

  • native-tls 启用平台本机 TLS 库 native-tls。
  • vendored-openssl 编译并静态链接 OpenSSL 的副本。请参阅 openssl 库的相应特性。
  • rustls-tls 启用替代 TLS 库 rustls。
  • email-check 启用使用 check-if-email-exists 库检查电子邮件地址。此功能需要 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
异步/并行 yes yes yes yes yes yes yes yes
JSON 输出 yes no yes yes yes maybe1 yes yes
静态二进制 yes no yes no no ️no no no
Markdown 文件 yes yes no no no yes yes no
HTML 文件 yes no no yes yes no yes no
文本文件 yes no no no no no no no
网站支持 yes no yes yes yes yes no yes
分块编码 yes maybe maybe maybe maybe no yes yes
GZIP 压缩 yes maybe maybe yes maybe yes maybe no
基本身份验证 yes no no yes no yes no no
自定义用户代理 yes no no yes no yes no no
相对 URL yes yes no yes yes yes yes yes
锚点/片段 yes no no no no yes yes no
跳过相对 URL yes no no maybe no no no no
包含模式 yes️ yes no yes no no no no
排除模式 yes no yes yes yes yes yes yes
处理重定向 yes yes yes yes yes yes yes yes
忽略不安全的 SSL yes yes yes no no yes no yes
文件通配符 yes yes no no yes no yes no
限制方案 yes no no yes no yes no no
自定义头信息 yes no yes no no no yes yes
摘要 yes yes yes maybe yes yes no yes
HEAD 请求 yes yes no yes yes yes no no
彩色输出 yes maybe yes maybe yes yes no yes
过滤状态码 yes yes no no no no yes no
自定义超时 yes yes yes no yes yes no yes
电子邮件链接 yes no no no no yes no no
进度条 yes yes no no no yes yes yes
重试和退避 yes no no no yes no yes no
跳过私有域名 yes no no no no no no no
用作库 yes yes no yes yes no yes no
静默模式 yes no no no yes yes yes yes
配置文件 yes no no no yes yes yes no
cookie yes no yes no no yes no yes
递归 no no yes yes yes yes yes no
惊人的 lychee 徽标 yes no no no no no no no

1 还支持其他机器可读格式，如 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
  • -$(pwd):/input 对 lychee 访问进行本地卷挂载。

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

Linux/macOS 命令行

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操作作为一个单独的仓库可用：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更快的办法，请与我们联系。

故障排除和解决方案

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

用户

如果您正在将lychee用于您的项目，请在此处添加。

鸣谢

lychee的第一个原型是在Hello Rust的第10集中构建的。感谢所有从开始就支持我们发展的GitHub和Patreon赞助商。还要感谢所有使这个项目更加成熟的大神级贡献者。

许可

lychee的许可协议为以下之一

任选其一。


🔼 返回顶部

依赖项

~32–51MB
~1M SLoC