ruff-integration

ruff 集成

将 ruff 集成到编辑器、pre-commit 钩子和 CI/CD 流水线中。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 ruff-linting……	在以下情况下改用 ruff-formatting……
设置 VS Code / 编辑器	配置 lint 规则	配置格式选项
添加 pre-commit 钩子	选择/忽略规则	引号样式、行长度
将 ruff 添加到 CI/CD	了解规则类别	格式差异
Docker/构建集成	修复 lint 违规	检查格式是否符合要求

VS Code 设置

// .vscode/settings.json
{
  "[python]": {
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    },
    "editor.defaultFormatter": "charliermarsh.ruff"
  },
  "ruff.lint.args": ["--select=E,F,B,I"],
  "ruff.importStrategy": "fromEnvironment"
}

# Install extension
code --install-extension charliermarsh.ruff

Pre-commit 集成

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.14.0
    hooks:
      - id: ruff-check
        args: [--fix]
      - id: ruff-format

pre-commit install           # Install hooks
pre-commit run --all-files   # Run manually
pre-commit autoupdate        # Update versions

GitHub Actions CI

# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]

jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/ruff-action@v3
        with:
          args: 'check --output-format github'

分别检查 lint 和格式：

jobs:
  ruff-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install ruff
      - run: ruff check --output-format github

  ruff-format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install ruff
      - run: ruff format --check --diff

配置优先级

1. 命令行参数（优先级最高）
2. 编辑器 LSP 设置
3. 当前目录中的 ruff.toml
4. 当前目录中的 pyproject.toml
5. 父目录中的配置（递归查找）
6. 用户配置：~/.config/ruff/ruff.toml
7. Ruff 默认值（优先级最低）

最佳实践

• 编辑器：启用保存时格式化，使用项目专属的 .vscode/settings.json
• Pre-commit：先运行 ruff-check --fix，再运行 ruff-format
• CI/CD：使用 --output-format github 为 PR 添加注释
• 性能：在 CI 中缓存 ruff，并在 pre-commit 中仅对更改的文件运行
• 团队：将编辑器/pre-commit 配置提交到版本控制中

Agent 优化

场景	命令
快速 lint 检查	ruff check --output-format github
格式检查	ruff format --check --diff
自动修复所有问题	ruff check --fix && ruff format
仅检查错误	ruff check --select E
CI 注释	ruff check --output-format github
JSON 输出	ruff check --output-format json
指定文件	ruff check --diff path/to/file.py

快速参考

# Editor
code --install-extension charliermarsh.ruff

# Pre-commit
pre-commit install && pre-commit run --all-files

# CI (GitHub Actions)
uses: astral-sh/ruff-action@v3

# Docker
docker run -v .:/app ghcr.io/astral-sh/ruff:0.14.0-alpine check /app

有关编辑器配置（Neovim、Zed、Helix）、GitLab/CircleCI/Jenkins CI、构建系统集成、Docker 设置、LSP 配置和迁移指南，请参阅 REFERENCE.md。