企业官网建设流程全解析

如何用 Docker 镜像 ghcr.io/astral-sh/ruff 在容器内执行 ruff check

【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff

当你想在容器环境里对 Python 代码做 lint，而不是在宿主机上安装 ruff 时，可以使用 Astral 官方发布的 Docker 镜像ghcr.io/astral-sh/ruff。它只包含ruff可执行文件（distroless 镜像），运行check后容器退出码会遵循 ruff 的约定：0表示未发现违规或违规已全部自动修复，1表示发现了违规，2表示配置或命令行参数无效、内部错误等异常终止。

镜像与可用标签

镜像按每个 release 打 tag，并保留latest指向最新发布。镜像基础分为几类（见 docs/integrations.md）：

• 默认 distroless 镜像：
  • ruff:latest
  • ruff:{major}.{minor}.{patch}，如ruff:0.6.6
  • ruff:{major}.{minor}，如ruff:0.6（该小版本下的最新 patch）
• 基于alpine:3.20：ruff:alpine、ruff:alpine3.20
• 基于debian:bookworm-slim：ruff:debian-slim、ruff:bookworm-slim
• 基于buildpack-deps:bookworm：ruff:debian、ruff:bookworm

非 distroless 镜像同样以版本 tag 发布，格式为ruff:{major}.{minor}.{patch}-{base}和ruff:{major}.{minor}-{base}，例如ruff:0.6.6-alpine。

在容器内执行 ruff check

官方给出的主路径命令是把当前项目目录挂载到容器内的/io，然后执行check（见 docs/installation.md）：

$ docker run -v .:/io --rm ghcr.io/astral-sh/ruff check

各部分的作用：

• -v .:/io：把宿主机当前目录挂载为容器内/io。ruff 镜像的构建文件 Dockerfile 中WORKDIR /io、ENTRYPOINT ["/ruff"]，所以容器启动后 ruff 直接在项目目录上工作，且镜像内所有路径都以/io为基准；
• --rm：任务结束后自动删除容器；
• check：追加在镜像名之后的参数会作为ruff的参数传入，等价于在宿主机上执行ruff check。

需要固定版本时，给镜像加版本 tag 即可：

$ docker run -v .:/io --rm ghcr.io/astral-sh/ruff:0.3.0 check

在启用 SELinux 的宿主机上，文档给出的替代写法是追加:Z标志，让挂载目录获得正确的 SELinux 标签：

$ docker run -v .:/io:Z --rm ghcr.io/astral-sh/ruff check

透传 ruff 的其它选项

因为镜像ENTRYPOINT就是/ruff，check之后的任意 ruff 参数都可以原样透传。常用的例如：

$ docker run -v .:/io --rm ghcr.io/astral-sh/ruff check --output-format=github .

--output-format可选值包括concise、full（默认）、json、json-lines、junit、grouped、github、gitlab、pylint、rdjson、azure、sarif。项目使用非默认配置文件时，可以用--config指向具体的 TOML 配置文件，例如：

$ docker run -v .:/io --rm ghcr.io/astral-sh/ruff check /io --config /io/ruff.toml

ruff 会识别挂载目录中的pyproject.toml、ruff.toml、.ruff.toml；不带--config时按文档描述的文件发现规则定位配置（见 docs/configuration.md）。

验证结果

命令跑完后按容器退出码判断：

• 退出码0：没有违规，或发现的违规全部被自动修复；
• 退出码1：存在违规（此时终端会列出违规明细）；
• 退出码2：ruff 异常终止，通常是配置无效、CLI 参数错误或内部错误，需要先修正参数或配置再重跑。

在脚本或 CI 里可以用echo $?或 shell 判断来检查退出码。另外两个影响退出码的选项（见 docs/linter.md）：

• --exit-zero：即使发现违规也以0退出（异常终止仍为2）；
• --exit-non-zero-on-fix：发现违规即以1退出，即使违规已全部自动修复。

在 GitLab CI 中使用该镜像

docs/integrations.md 给出了用ghcr.io/astral-sh/ruff:0.16.6-alpine作为 CI 镜像、生成 GitLab codequality 报告的示例（节选自文档原文）：

.base_ruff: stage: build interruptible: true image: name: ghcr.io/astral-sh/ruff:0.16.6-alpine before_script: - cd $CI_PROJECT_DIR - ruff --version Ruff Check: extends: .base_ruff script: - ruff check --output-format=gitlab --output-file=code-quality-report.json artifacts: reports: codequality: $CI_PROJECT_DIR/code-quality-report.json

注意这条路径与docker run的写法不同：在 alpine 镜像内直接调用ruff，工作目录由$CI_PROJECT_DIR决定，并用--output-file把报告写回项目目录以便收集为 artifact。

限制

• 默认镜像是 distroless 的，只含ruff二进制（构建基于 Dockerfile，最终阶段FROM scratch），不要在容器内假设存在 shell、Python 解释器或其它工具；需要基础环境时选用 alpine 或 debian 变体 tag。
• 容器内 ruff 能看到的文件就是你挂载的内容；-v .:/io只挂载当前目录，跨目录的项目结构需要在挂载时自行覆盖。

【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff