haydenbleasel/ultracite · 上手攻略

是什么

Ultracite 是一个「开箱即用、零配置」的 JavaScript / TypeScript 代码检查与格式化预设。它的核心思路是把 ESLint、Biome、Oxlint 这些主流 lint/format 工具链中最常见的「已经被反复验证过的规则」打包成一份共享配置，让用户只需一条命令就把项目接入一套生产级别的代码规范，而不必从零手写 .eslintrc / biome.json / .oxlintrc.json。

⚠️ 注意：仓库 README 当前定位是「production-grade preset for ESLint, Biome, and Oxlint」，并明确支持 Prettier、Stylelint 与 Oxfmt；它本身不是 linter，而是 linter 配置分发器。

解决什么问题

对绝大多数前端 / Node 工程而言，配置 ESLint + Prettier 一直是个「重复劳动 + 反复踩坑」的工程：

  1. 选规则集合：airbnb、standard、google 各自成体系，新人很难判断；
  2. 装插件：TypeScript、React、Next.js、JSX a11y、import 顺序……插件版本和 peerDependencies 互相冲突是常态；
  3. 编辑器集成：VSCode、Cursor、JetBrains、Neovim 各有各的 settings；
  4. 跟 AI 工具协作：Cursor、Claude Code、GitHub Copilot 都有自己的 .cursorrules / AGENTS.md，规则不一致就出现「人写的代码被 AI 改坏」。

Ultracite 把上述四件事统一成一条 npx ultracite init：选定工具链 → 装依赖 → 写好配置 → 同步生成 AI agent 上下文（AGENTS.md 等）。一份 AGENTS.md 同时给人类和 AI 读，规则不分裂。

快速安装

⚠️ 版本以 README 与 npm 当前发布版本为准，写稿时为 v5.x 系列（详见 npm 与官网 changelog）；建议执行前先 npx ultracite@latest --version 校对一次。

# 在项目根目录执行，进入交互式初始化
npx ultracite init

# 非交互模式（适合 CI / 容器）
npx ultracite init --linter biome --pm npm --editors vscode --frameworks react --quiet

参数说明（摘自主流用法，详细见官网 CLI reference）：

  • --linter <biome|eslint|oxlint>：选哪一套底层工具链
  • --pm <npm|pnpm|yarn|bun>：包管理器，自动检测可用
  • --editors <vscode|cursor|jetbrains|universal ...>：要写入配置的编辑器列表
  • --agents <claude|copilot|cursor|gemini|universal ...>：要生成 AI 上下文文件的 agent
  • --frameworks <react|next|vue|svelte ...>：启用框架相关规则
  • --type-aware：开启 TypeScript 类型感知 lint（⚠️ 会拖慢速度）
  • --js-plugins：可选 Oxlint JS 插件（eslint-plugin-github / eslint-plugin-sonarjs / oxlint-plugin-react-doctor）
  • --install-skill：把 Ultracite 作为可复用的 skill 安装
  • --skip-install：只写配置不装依赖

包管理器偏好：

pnpm dlx ultracite init
yarn dlx ultracite init
bunx ultracite init

核心用法

# 只检查，不改文件（CI 推荐）
ultracite check

# 自动修复（开发推荐，pre-commit hook 推荐）
ultracite fix

# 只跑某个子集
ultracite fix src/components src/utils

# 把兜不住的剩余问题交给 Claude Code / Codex 自动修
ultracite fix --claude
ultracite fix --codex

# 自检环境
ultracite doctor

⚠️ --claude / --codex 需要本机装好对应 CLI，Ultracite 会逐文件丢给它们，再 lint 验证一遍再算完成——这部分行为依赖本地 CLI 版本，写自动化脚本前最好在沙箱环境里先跑一次 ultracite fix --claude --dry-run（如有）确认行为。

AI agent 上下文是 Ultracite 的差异化点。ultracite init --agents universal 会写入一份 AGENTS.md，里面用自然语言 + 规则编号告诉 Claude Code / Cursor / Copilot「这个项目禁止哪些写法」。这样 AI 改的代码第一轮就不会触发 lint，从源头减少来回。

典型适用场景

  1. 新项目冷启动：不要在「先装 ESLint 还是 Biome」「要不要 Prettier」「要不要 Stylelint」上纠结，一条命令结束。
  2. 团队规范统一：把 Ultracite 引入 monorepo，所有子包共享一套规则，杜绝「前端 lint 松、后端 lint 紧」的割裂。
  3. AI 协作规范化：大量使用 Cursor / Claude Code / Copilot 的团队，Ultracite 一次性把 AGENTS.md + cursorrules 写齐。
  4. 存量项目升级：从「半残的 ESLint + 半残的 Prettier」迁到 Biome / Oxlint 提速。
  5. CI 集成：ultracite check --quiet 进 GitHub Actions 失败即红。

坑与注意

⚠️ 版本与 lockfile：Ultracite 本身依赖下游 ESLint、Biome、Oxlint 的 peer 范围。升级前先跑 ultracite doctor，再升下游包，否则容易出现「升级 ESLint 后插件不兼容」的经典场景。

⚠️ --type-aware 性能成本：开启后 lint 速度会显著下降，建议只在 CI 跑、本地不开。

⚠️ --claude / --codex 行为依赖：把修复工作丢给外部 CLI 听起来美好，但实际上是「外部 CLI 改 → Ultracite lint → 不通过再改」的循环。⚠️ 在大型 monorepo 上单次 round-trip 可能在分钟级，且消耗外部 CLI 的 token 配额；CI 中默认不要开。

⚠️ 自定义规则的代价：Ultracite 的卖点是「共享配置」，自己 .eslintrc 写一堆 override 等于退回到「自己维护一套规范」。如果团队就是要 Airbnb 或 Standard 风格，可以直接装对应 eslint-config-*，未必需要 Ultracite 这一层。

⚠️ 框架选项的覆盖度：--frameworks react/next/vue/svelte 是 preset 级别开关，不等于帮你装 React/Vue 框架；要在已有框架项目里跑才有意义。

⚠️ Oxlint 路径仍在演进：Oxlint 生态比 ESLint 年轻，部分老插件（如 @typescript-eslint 复杂规则）未完全覆盖；看重规则深度仍以 ESLint 为首选。

⚠️ node 版本要求：Ultracite 自身需要较新的 Node（README 标 Node 18+；部分子功能如 --claude 集成需要更新的运行时）。在老 Node 镜像里 init 会直接报错。

与同类对比

工具 定位 优点 短板
Ultracite（本项目） 零配置 preset，分发器 一条命令接入；多工具链支持；AI 上下文同步 自定义要小心；版本耦合下游
直接装 eslint-config-airbnb 共享 ESLint config 规则成熟、社区共识 仍要自己装 Prettier / 写脚本 / 配编辑器
直接用 Biome 单二进制工具 极快、零依赖 与 ESLint 插件生态不通，覆盖深度有差距
直接用 Oxlint Rust 单二进制 极快、Oxc 生态整合 规则覆盖较新，部分场景规则不够
Prettier alone 纯格式化 共识度最高 不做 lint；与 ESLint 规则有重叠需要关掉冲突

简单说：Ultracite 不是让你在「ESLint / Biome / Oxlint」里二选一，而是把这三者的「开箱规则集 + AI 协作上下文」封装到一起。⚠️ 如果你已经对 eslint-config-* 有强偏好、或项目规则非常定制，Ultracite 的价值会打折扣。

一句话推荐结论

适合「想今天就让项目有 lint + 还想让 AI 改代码不出错」的 JS/TS 团队；不是给追求极致自定义规则的人准备的。