名称: ultracite 描述: Ultracite 多提供者代码检查/格式化工具（Biome、ESLint、Oxlint）。适用于 v6/v7 设置、提供者选择、Git 钩子、MCP 集成、AI 钩子、迁移，或遇到配置、类型感知检查、单仓库错误。许可证: MIT 元数据: 版本: 2.0.0 依赖项: ultracite: 最新 “@biomejs/biome”: “>=1.9.0” eslint: “>=8.0.0（当使用 ESLint 提供者）” oxlint: “>=0.1.0（当使用 Oxlint 提供者）” 运行时: Node.js v14.18+（推荐 v18+）包管理器: - bun（首选） - npm - pnpm - yarn 支持框架: - React - Next.js - Vue - Svelte - Solid - Angular - Remix - Qwik - Astro Git 钩子管理器: - husky - lefthook - lint-staged 支持编辑器: - VS Code（Biome 扩展） - Cursor - Claude Code - Zed - Cline - Windsurf 关键词: - ultracite - biome - 代码检查 - 格式化 - 代码质量 - eslint 替代 - prettier 替代 - typescript 严格模式 - rust 检查器 - 快速格式化器 - 自动修复 - git 钩子 - 预提交 - husky - lefthook - lint-staged - react 检查 - nextjs 检查 - vue 检查 - svelte 检查 - 单仓库检查 - turborepo - AI 编码规则 - cursor 规则 - claude code 规则 - copilot 指令 - 无障碍检查 - 安全检查 - 性能检查 - jsx 检查 - hooks 检查 - 从 eslint 迁移 - 从 prettier 迁移 - biome.jsonc - 零配置 - 代码格式化 - 导入排序 - 未使用导入 - 严格相等 - 类型安全 - oxlint - oxfmt - eslint 集成 - 多提供者 - 提供者选择 - mcp 服务器 - ai 钩子 - 类型感知检查 - ultracite 诊断 - 程序化使用 - v6 升级 - v7 升级 - 预设迁移

Ultracite 技能

快速、零配置的现代 JavaScript/TypeScript 项目代码检查和格式化

概述

Ultracite 是一个统一的代码检查和格式化解决方案，支持多种提供者：Biome（默认，基于 Rust）、ESLint+Prettier+Stylelint 和 Oxlint+Oxfmt。它提供框架特定的预设和零配置默认值，用更快、更简单的替代方案取代传统的 ESLint+Prettier 设置。Ultracite 在后台隐形运行，每次保存时自动格式化代码和应用修复。

版本 7 变化：多提供者架构、预设路径迁移、MCP 服务器支持、AI 钩子 版本 6 变化：引入框架特定预设（React、Next.js、Vue、Svelte 等）

核心目标

闪电般快速性能：利用 Biome 的 Rust 实现实现即时检查/格式化
零配置设计：附带 200+ 个针对现代 TypeScript 开发优化的合理默认值
简单性和隐形性：以最少的用户交互操作
类型安全：强制执行 TypeScript 严格模式和全面的 null/undefined 处理
工具兼容性：与其他开发工具一起工作无冲突

关键优势 vs 替代方案

vs ESLint + Prettier：

10-100 倍更快性能（Rust vs JavaScript）
单一工具而非两个
无需配置
默认保存时自动修复
内置 TypeScript 严格模式

vs 单独 Biome：

200+ 个预配置规则
框架特定预设（React、Next.js、Vue、Svelte）
AI 编辑器集成（Cursor、Claude Code、Copilot）
Git 钩子集成
迁移工具

何时使用此技能

✅ 理想项目

在以下情况下使用 Ultracite：

启动新的 JavaScript/TypeScript 项目
使用 React、Next.js、Vue、Svelte 或其他现代框架构建
在单仓库工作（Turborepo、Nx、Lerna）
团队希望一致的格式化而无需争论
性能关键（大型代码库、CI/CD 优化）
从 ESLint + Prettier 迁移到更快解决方案
使用 AI 编码助手（Cursor、Claude Code、Windsurf）
TypeScript 项目需要严格类型安全
有无障碍要求（ARIA、语义 HTML）的项目

⚠️ 考虑替代方案当

有限框架支持：

需要 Angular/Ember 特定规则（Biome 支持基本）
需要高级 CSS 检查（仍推荐 Stylelint）

专业要求：

需要特定 ESLint 插件未在 Biome 中复制
需要 CSS 中的属性排序（Stylelint 功能）
团队有大量自定义 ESLint 配置

遗留项目：

具有自定义 ESLint 规则的大型代码库（需要迁移工作）
具有广泛 Prettier 自定义的项目

详细限制和解决方法，见：references/limitations-and-workarounds.md

交互组件

此技能提供交互命令和自主代理以简化工作流：

命令

/ultracite:doctor - 验证项目设置，检查 v6→v7 预设路径，检测冲突
/ultracite:migrate - 交互迁移向导（ESLint/Prettier → Ultracite、v6→v7 升级）

代理

config-validator - 分析 biome.jsonc 的语法、预设路径、规则冲突、性能
migration-assistant - 指导 ESLint/Prettier 迁移，包括规则映射和差距分析

完整交互功能文档见 README.md。

选择提供者

Ultracite v7 支持三种检查提供者。根据需求选择：

🚀 Biome（默认） - 推荐大多数项目

速度：最快（比 ESLint 快 10-100 倍）
设置：零配置，200+ 预设规则
最适合：新项目、TypeScript 优先开发、性能关键构建
限制：比 ESLint 规则少，基本 CSS/SCSS 支持

🔧 ESLint + Prettier + Stylelint - 推荐最大兼容性

速度：较慢但生态系统成熟
设置：需要更多配置
最适合：具有现有 ESLint 插件的项目、高级 CSS/SCSS 检查需求
限制：基于 JavaScript（较慢），需要多个工具

⚡ Oxlint + Oxfmt - 推荐最大速度

速度：最快检查（甚至比 Biome 仅检查更快）
设置：类型感知检查与 TypeScript 集成
最适合：大型 TypeScript 代码库、类型安全关键项目
限制：较新生态系统，比 ESLint 规则少

提供者选择在初始化时：

bun x ultracite init --linter biome   # 默认
bun x ultracite init --linter eslint  # ESLint + Prettier + Stylelint
bun x ultracite init --linter oxlint  # Oxlint + Oxfmt

加载提供者特定文档：

Biome：references/provider-biome.md
ESLint：references/provider-eslint.md
Oxlint：references/provider-oxlint.md

版本迁移指南

从 v6 升级到 v7

重大变化：v7 中预设路径已更改。

v6 路径（旧）：

{
  "extends": ["ultracite/core", "ultracite/react"]
}

v7 路径（新）：

{
  "extends": ["ultracite/biome/core", "ultracite/biome/react"]
}

迁移步骤：

更新 ultracite 包：bun update ultracite
更新 biome.jsonc 中的预设路径（添加 /biome/ 段）
运行 npx ultracite doctor 验证配置
测试检查：npx ultracite check .

新 v7 功能：

多提供者支持（Biome、ESLint、Oxlint）
MCP 服务器集成用于 AI 助手
AI 钩子（AI 编辑后自动格式化）
类型感知检查（Oxlint）
ultracite doctor 诊断命令

加载完整 v7 迁移指南：references/v7-migration.md

从 v5 升级到 v6

关键变化：引入框架特定预设。

v5 方法（旧）：

{
  "extends": ["ultracite/core"]
}

v6 方法（新）：

{
  "extends": ["ultracite/core", "ultracite/react"]  // 框架预设
}

加载完整 v6 迁移指南：references/v6-migration.md

项目适用性评估

当调用此技能时，扫描项目并评估：

检查现有工具：

# 检查 ESLint
ls -la .eslintrc* eslint.config.* package.json | grep eslint

# 检查 Prettier
ls -la .prettierrc* prettier.config.* package.json | grep prettier

# 检查 Biome
ls -la biome.json* package.json | grep biome

识别框架：
- 检查 package.json 中的 react、next、vue、svelte 等。
- 推荐适当预设
评估项目大小：
- 大型项目（1000+ 文件）最受益于 Rust 性能
- 小项目可能不会注意到速度差异
检查 TypeScript 配置：
- 如果 tsconfig.json 存在，注意 Ultracite 需要 strictNullChecks: true
- 警告如果禁用（将生成许多警告）

推荐或警告：

✅ 推荐：此 TypeScript + React 项目是 Ultracite 的理想选择
- 500+ 文件将受益于 Rust 性能
- 可用 React 预设
- 可以替换现有 ESLint + Prettier 设置

⚠️ 考虑：此项目使用高级 ESLint 插件
- 自定义规则：eslint-plugin-custom-security
- 可能需要保留 ESLint 用于这些特定规则
- 可以仅使用 Ultracite 进行格式化

安装与设置

先决条件

Node.js v14.18+（推荐 v18+）
包管理器：Bun（首选）、npm、pnpm 或 yarn
项目根目录中的 package.json 文件

快速开始（交互式）

# 使用 Bun（首选速度）
bun x ultracite init

# 带提供者选择（v7+）
bun x ultracite init --linter biome   # 默认，最快
bun x ultracite init --linter eslint  # ESLint + Prettier + Stylelint
bun x ultracite init --linter oxlint  # Oxlint + Oxfmt（类型感知）

# 使用 npm
npx ultracite init

# 使用 pnpm
pnpm dlx ultracite init

# 使用 yarn
yarn dlx ultracite init

交互式设置将：

提示提供者选择（Biome、ESLint、Oxlint） - 仅 v7+
安装 Ultracite 和提供者依赖项
提示框架选择（React、Next.js、Vue 等）
询问编辑器设置（VS Code、Cursor 等）
提供 AI 代理规则安装（Cursor、Claude Code、Copilot）
提示 Git 钩子集成（Husky、Lefthook、lint-staged）
提供从现有工具迁移（ESLint、Prettier）
创建/合并配置文件（biome.jsonc、.eslintrc.js 等）
更新 .vscode/settings.json 用于编辑器集成
在 tsconfig.json 中启用 strictNullChecks（如果是 TypeScript）

非交互式设置（CI/自动化）

# 自动检测设置，跳过提示
bunx ultracite init --quiet

# 明确指定选项（v7+）
bunx ultracite init \
  --linter biome \
  --pm bun \
  --frameworks react,next \
  --editors vscode \
  --agents cursor,claude \
  --integrations husky \
  --migrate eslint,prettier \
  --quiet

可用标志：

--linter：提供者选择（biome、eslint、oxlint） - 仅 v7+
--pm：包管理器（bun、npm、pnpm、yarn）
--frameworks：react、next、solid、vue、qwik、angular、remix、svelte
--editors：vscode、zed
--agents：cursor、claude、cline、copilot、windsurf 等
--integrations：husky、lefthook、lint-staged
--migrate：eslint、prettier、biome
--quiet：跳过所有提示（当 CI=true 时自动启用）

手动设置（高级）

# 1. 安装依赖项
bun add -D ultracite @biomejs/biome

# 2. 创建 biome.jsonc
cat > biome.jsonc << 'EOF'
{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": ["ultracite/core"]
}
EOF

# 3. 创建 VS Code 设置
mkdir -p .vscode
cat > .vscode/settings.json << 'EOF'
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "quickfix.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}
EOF

# 4. 启用 TypeScript 严格模式
# 添加到 tsconfig.json：
{
  "compilerOptions": {
    "strictNullChecks": true
  }
}

验证安装

# 检查安装
bunx ultracite doctor

# 预期输出：
# ✔ Biome 已安装
# ✔ 找到配置文件：biome.jsonc
# ✔ 编辑器集成已配置
# ✔ TypeScript 严格模式已启用

配置

基本配置

文件结构：

项目根目录/
├── biome.jsonc              # 主配置
├── .vscode/settings.json    # VS Code 集成
├── tsconfig.json            # TypeScript 配置（需要 strictNullChecks）
└── package.json

最小 biome.jsonc：

{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": ["ultracite/core"],

  // 可选：添加框架预设
  // "extends": ["ultracite/core", "ultracite/react"],

  // 可选：自定义规则
  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "off"  // 禁用特定规则
      }
    }
  },

  // 可选：排除文件
  "files": {
    "ignore": ["dist", "build", "coverage", "**/*.generated.ts"]
  }
}

框架预设

ultracite/react：React Hooks、JSX 无障碍、组件最佳实践
ultracite/nextjs：React + Next.js App Router、图像优化、文档结构
ultracite/vue：Vue 3 Composition API、模板语法、响应性
ultracite/svelte：Svelte 4/5 语法、响应声明

用法：

{
  "extends": ["ultracite/core", "ultracite/react"]
}

核心预设

ultracite/core 预设包括 200+ 规则，跨 7 个类别：

无障碍：ARIA 验证、语义 HTML、键盘导航
正确性：类型安全、未使用代码移除、详尽依赖
性能：代码优化、桶文件警告
安全：防止 eval()、XSS 风险、不安全模式
样式：一致模式、const 偏好、导入组织
可疑：捕获松散相等、调试器语句、拼写错误
复杂性：认知复杂性限制

格式化默认值：2 空格、80 字符/行、LF 结尾、单引号

详细框架预设、规则描述和高级配置，见：references/configuration-guide.md

使用

IDE 集成（推荐）

VS Code 设置：

安装 Biome 扩展：biomejs.biome

验证 .vscode/settings.json：

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "quickfix.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}

禁用冲突扩展（ESLint、Prettier）

功能：

保存时自动格式化
保存时自动修复（移除未使用导入、修复顺序、应用严格相等）
粘贴时格式化
问题面板用于不可修复问题
通过灯泡指示器快速修复

CLI 使用

检查代码（仅检查）：

bunx ultracite check
bunx ultracite check src/
bunx ultracite check --diagnostic-level error  # 仅错误

修复代码（自动修复）：

bunx ultracite check --write
bunx ultracite check --write src/

格式化代码（仅格式化）：

bunx ultracite format --write
bunx ultracite format --write src/

Package.json 脚本：

{
  "scripts": {
    "lint": "ultracite check",
    "lint:fix": "ultracite check --write",
    "format": "ultracite format --write"
  }
}

Git 钩子集成

Ultracite 自动检测并集成：

Husky：基于 Node.js 的钩子管理器
Lefthook：快速 Go 基钩子管理器
lint-staged：仅对暂存文件运行检查器

快速设置：

# Husky
bunx ultracite init --integrations husky

# Lefthook
bunx ultracite init --integrations lefthook

# lint-staged
bunx ultracite init --integrations lint-staged

示例 .husky/pre-commit：

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

ultracite check --staged --write

完整 Git 钩子设置指南（Husky、Lefthook、lint-staged），见：references/git-hooks-setup.md

AI 编辑器规则

Ultracite 生成 AI 编辑器规则，教授 AI 助手您的检查/格式化标准。

支持编辑器：

Cursor（.cursorrules）
Claude Code（.windsurfrules）
GitHub Copilot（.github/copilot-instructions.md）
Continue.dev（.continuerules）
Codeium（.codeiumrules）
Zed（.zedrules）

生成规则：

bunx ultracite generate-ai-rules
bunx ultracite generate-ai-rules --all  # 所有编辑器
bunx ultracite generate-ai-rules --editor=cursor  # 特定编辑器

完整 AI 编辑器集成指南和自定义，见：references/ai-editor-integration.md

单仓库支持

Ultracite 为单仓库优化：

共享基础配置
包特定覆盖
Turborepo/Nx 缓存集成
大型工作区性能优化

示例单仓库结构：

单仓库/
├── biome.json              # 共享基础配置
├── apps/
│   └── web/
│       └── biome.json      # Next.js 特定覆盖
└── packages/
    └── ui/
        └── biome.json      # React 特定覆盖

完整单仓库设置、Turborepo/Nx 集成和性能提示，见：references/monorepo-configuration.md

从 ESLint/Prettier/Biome 迁移

自动迁移：

bunx ultracite migrate eslint
bunx ultracite migrate prettier
bunx ultracite migrate biome

手动迁移：

分析当前配置
映射规则到 Biome 等效规则
创建具有等效规则的 biome.json
更新 package.json 脚本
移除旧依赖项
彻底测试

完整迁移指南和详细规则映射，见：references/migration-guides.md

已知限制

CSS/SCSS：Biome 不检查 CSS。解决方法：使用 Stylelint 框架缺口：有限 Angular/Astro 支持。解决方法：使用 ultracite/core + 手动规则 ESLint 插件：许多 ESLint 插件没有 Biome 等效。解决方法：运行 ESLint 与 Ultracite 并行用于特定插件 文件类型：无 Markdown、YAML、HTML 检查。解决方法：使用专用工具（markdownlint、yamllint、htmlhint）

完整限制列表和详细解决方法，见：references/limitations-and-workarounds.md

故障排除

常见问题：

VS Code 不保存时格式化 → 安装 Biome 扩展，配置设置
ESLint 冲突 → 禁用 ESLint 或选择性运行
解析错误 → 在 biome.json 中配置 JSX 支持
预提交钩子失败 → 使用 bunx 而非全局安装
CI 失败 → 固定 Bun/Node 版本，增加内存限制

完整故障排除指南，见：references/troubleshooting.md

模板与脚本

初始设置脚本

见 scripts/install-ultracite.sh 用于自动化设置。

迁移脚本

见 scripts/migrate-to-ultracite.sh 用于 ESLint/Prettier 迁移。

示例配置

见 references/ 目录：

configuration-guide.md：框架预设和规则细节
git-hooks-setup.md：Husky、Lefthook、lint-staged 设置
ai-editor-integration.md：Cursor、Claude Code、Copilot 规则
monorepo-configuration.md：Turborepo、Nx、pnpm 工作区
migration-guides.md：ESLint、Prettier、Biome 迁移
troubleshooting.md：常见问题和解决方案
limitations-and-workarounds.md：已知缺口和修复

包版本

当前版本（验证 2025-11-27）：

ultracite：最新
@biomejs/biome：>=1.9.0

检查更新：

npm view ultracite version
npm view @biomejs/biome version

更新：

bun update ultracite @biomejs/biome

资源

官方文档：

示例：

https://www.ultracite.ai/examples

故障排除：

社区：

GitHub Issues：https://github.com/ultracite/ultracite
Biome Discord：https://discord.gg/biome

何时加载参考

根据用户问题或任务需求按需加载参考文件：

references/provider-biome.md：当用户询问：

Biome 提供者特定
仅 Biome 配置
Biome 性能优化
Biome 预设路径（v7：ultracite/biome/*）
Biome 规则自定义

references/provider-eslint.md：当用户询问：

ESLint 提供者设置
ESLint + Prettier + Stylelint 集成
ESLint 插件配置
ESLint 迁移到 Ultracite
高级 CSS/SCSS 检查

references/provider-oxlint.md：当用户询问：

Oxlint 提供者设置
类型感知检查功能
Oxlint 性能优势
Oxlint vs Biome 比较
TypeScript 集成

references/v6-migration.md：当用户询问：

从 v5 升级到 v6
框架预设介绍
v6 配置变化
v6 重大变化

references/v7-migration.md：当用户询问：

从 v6 升级到 v7
预设路径迁移（ultracite/core → ultracite/biome/core）
多提供者设置
v7 重大变化
ultracite doctor 命令

references/mcp-integration.md：当用户询问：

MCP 服务器设置
通过 MCP 的 AI 助手集成
模型上下文协议
MCP 服务器配置

references/ai-hooks.md：当用户询问：

AI 钩子设置（区别于 AI 规则）
AI 编辑后自动格式化
编辑器钩子配置
后编辑格式化自动化

references/configuration-guide.md：当用户询问：

框架预设（React、Next.js、Vue、Svelte）
核心预设规则（200+ 规则分解）
规则自定义方法
文件排除模式
高级配置

references/git-hooks-setup.md：当用户询问：

预提交钩子
Husky 集成
Lefthook 集成
lint-staged 设置
CI/CD 集成
钩子故障排除

references/ai-editor-integration.md：当用户询问：

AI 编辑器规则生成
Cursor 集成
Claude Code 集成
GitHub Copilot 设置
自定义 AI 规则
编辑器特定设置

references/monorepo-configuration.md：当用户询问：

单仓库设置
Turborepo 集成
Nx 集成
包特定覆盖
工作区配置
性能优化

references/migration-guides.md：当用户询问：

ESLint 迁移
Prettier 迁移
Biome 迁移
规则映射
迁移检查清单
迁移后步骤

references/troubleshooting.md：当用户询问：

VS Code 问题
ESLint/Prettier 冲突
解析错误
预提交钩子失败
CI 失败
TypeScript 严格性错误
安装问题
性能问题

references/limitations-and-workarounds.md：当用户询问：

CSS 检查
框架支持缺口
ESLint 插件生态系统
文件类型支持
编辑器集成
迁移限制

总结

Ultracite 提供统一的代码检查和格式化解决方案，支持多提供者：

✅ 使用当：

启动新项目
使用 React/Next/Vue/Svelte 构建
在单仓库工作
希望一致的格式化而无需配置
性能重要（Biome/Oxlint 提供者）
需要 ESLint 兼容性（ESLint 提供者）
使用 AI 编码助手
需要类型感知检查（Oxlint）

⚠️ 考虑替代方案当：

需要特定 ESLint 插件任何提供者不支持
需要高级 CSS 检查（尽管 ESLint 提供者包括 Stylelint）
需要遗留框架支持

关键优势：

多提供者：选择 Biome（最快）、ESLint（最兼容）或 Oxlint（类型感知）
版本 7：预设路径迁移、MCP 服务器、AI 钩子、多提供者架构
版本 6：框架特定预设（React、Next.js、Vue、Svelte 等）
比传统 ESLint + Prettier 快 10-100 倍（Biome/Oxlint）
零配置（200+ 规则预配置用于 Biome）
框架特定预设
AI 编辑器集成 + AI 钩子
Git 钩子支持
TypeScript 严格模式强制执行

安装：

bun x ultracite init --linter biome   # 默认（v7+）
bun x ultracite init --linter eslint  # ESLint 提供者（v7+）
bun x ultracite init --linter oxlint  # Oxlint 提供者（v7+）

最常见工作流：

用 bun x ultracite init 安装
选择框架预设（React、Next.js 等）
选择 Git 钩子集成（Husky、Lefthook、lint-staged）
启用 AI 编辑器规则（Cursor、Claude Code、Copilot）
可选从 ESLint/Prettier 迁移
保存时自动格式化编码
用预提交钩子提交确保质量

记住：

安装前始终检查现有 Git 钩子管理器
评估项目适用性（扫描 ESLint/Prettier/框架）
基于项目特征推荐或警告
在 TypeScript 项目中启用 strictNullChecks
使用框架特定预设获得最佳结果
根据用户问题按需加载参考文件