lycheeverse/lychee

Lychee 链接检查器 Docker 镜像文档

镜像概述和主要用途

Lychee 是一个用 Rust 编写的快速、异步、资源友好型链接检查器。该 Docker 镜像提供了一个便捷的方式来部署和运行 Lychee，用于检测 Markdown、HTML、reStructuredText 或任何其他文本文件及网站中的损坏超链接和邮件地址。

作为命令行工具、库和 GitHub Action 可用，Lychee 专为高效链接验证设计，适合集成到 CI/CD 流程、文档维护工作流或定期网站审计中。

核心功能和特性

性能优势

• 异步并行处理：高效利用系统资源，快速检查大量链接
• 资源友好：低内存占用和 CPU 使用率，适合各种环境
• 静态二进制：无需依赖外部运行时，容器内即可独立运行

链接检查能力

• 多格式支持：Markdown、HTML、reStructuredText 及各类文本文件
• 多协议支持：HTTP/HTTPS、文件系统路径、邮件地址
• 片段检查：可验证 URL 中的锚点（#fragment）是否存在
• 邮件验证：检查电子邮件地址有效性（需启用对应功能）

高级功能

• 缓存支持：本地磁盘缓存请求结果，加快重复检查速度
• 认证支持：基础认证、GitHub Token 集成，解决访问限制问题
• 自定义配置：通过命令行参数或配置文件定制检查行为
• 灵活过滤：包含/排除模式、状态码过滤、私有 IP 排除
• TLS 选项：支持不安全连接（用于测试环境）和自定义 CA 证书

输出与报告

• 多种输出格式：简洁、详细、JSON、Markdown 等报告格式
• 彩色输出：直观区分链接状态（正常/损坏/警告）
• 摘要统计：提供检查结果汇总，包括总链接数、损坏数、跳过数等
• 进度指示：实时显示检查进度，适合大型项目

使用场景和适用范围

开发与文档维护

• 本地文档链接验证（README、API 文档等）
• 静态网站生成前的链接检查（Hugo、Jekyll、Next.js 等）
• 代码仓库中的链接审计（检测过时的外部引用）

CI/CD 集成

• 提交/PR 触发的自动化链接检查
• 定期 scheduled 任务检查网站健康状态
• 发布前的文档完整性验证

网站与内容管理

• 博客文章链接有效性检查
• 知识库/文档系统维护
• 电子商务网站产品链接验证
• ***/教育机构网站合规性检查

特殊环境使用

• 离线模式：仅检查本地文件，阻止网络请求
• 受限网络环境：通过代理服务器检查外部链接
• 大型项目：递归检查目录结构中的所有支持文件

安装方法

获取镜像

bash
docker pull lycheeverse/lychee

镜像标签

• latest：基于 Debian 的稳定版本（默认）
• latest-alpine：基于 Alpine 的轻量级版本
• 特定版本标签（如 v0.14.3）：指定版本

详细使用方法和配置说明

基本用法

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

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

Windows PowerShell：

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

检查特定文件

bash
# 检查单个文件
docker run --init -it --rm -v $(pwd):/input lycheeverse/lychee /input/README.md

# 检查多个文件
docker run --init -it --rm -v $(pwd):/input lycheeverse/lychee /input/docs/*.md

检查网站

bash
docker run --init -it --rm lycheeverse/lychee https://example.com

Docker Compose 配置

创建 docker-compose.yml 文件：

yaml
version: '3'
services:
  lychee:
    image: lycheeverse/lychee
    volumes:
      - ./docs:/input
    working_dir: /input
    command: ["--format", "detailed", "."]
    environment:
      - GITHUB_TOKEN=${GITHUB_TOKEN}
      # 可选：设置代理
      # - HTTP_PROXY=http://proxy:8080
      # - HTTPS_PROXY=http://proxy:8080

运行：

bash
docker-compose run --rm lychee

高级用法示例

离线模式（仅检查本地链接）

bash
docker run --init -it --rm -v $(pwd):/input lycheeverse/lychee --offline /input

包含邮件地址检查

bash
docker run --init -it --rm -v $(pwd):/input lycheeverse/lychee --include-mail /input/contacts.md

JSON 输出（便于自动化处理）

bash
docker run --init -it --rm -v $(pwd):/input lycheeverse/lychee --format json /input | jq '.'

使用配置文件

创建 lychee.toml 配置文件：

toml
exclude = [
  "https://example.com/ignore-this-link",
  "mailto:ignore@example.com"
]
accept = ["200..=299", "403", "429"]
timeout = 10

运行：

bash
docker run --init -it --rm -v $(pwd):/input lycheeverse/lychee --config /input/lychee.toml /input

GitHub 令牌（避免速率限制）

bash
docker run --init -it --rm -e GITHUB_TOKEN=your_token_here lycheeverse/lychee https://github.com/your/repo

命令行参数

环境变量

故障排除与解决方法

常见问题

1. GitHub 链接速率限制

   • 解决方案：提供 GitHub 令牌，使用 --github-token 参数或 GITHUB_TOKEN 环境变量

2. SSL/TLS 证书错误

   • 解决方案：使用 -i, --insecure 参数禁用证书验证（仅测试环境）

3. 检查大型网站时性能问题

   • 解决方案：减少并发数 --max-concurrency，增加超时 --timeout，启用缓存 --cache

4. 邮件检查功能不工作

   • 确认：邮件检查需要 native-tls 特性，默认已启用
   • 注意：部分邮件提供商可能阻止批量检查

5. 容器内无法访问本地网络资源

   • 解决方案：使用 --network=host（需谨慎）或正确配置端口映射

资源与支持

• https://lycheeverse.github.io
• https://github.com/lycheeverse/lychee
• https://github.com/lycheeverse/lychee/issues
• https://github.com/lycheeverse/lychee/blob/master/lychee.example.toml

许可证

Lychee 采用 https://github.com/lycheeverse/lychee/blob/master/LICENSE%E3%80%82