ultracite

Ultracite 技能

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

概述

Ultracite 是一款统一的代码检查与格式化解决方案，支持多个提供方：Biome（默认，基于 Rust）、ESLint+Prettier+Stylelint 和 Oxlint+Oxfmt。它提供框架专属预设和零配置默认设置，可替代传统的 ESLint+Prettier 配置，成为更快速、更简单的选择。Ultracite 在后台隐式运行，每次保存时都会自动格式化代码并应用修复。

Version 7 变更：多提供方架构、预设路径迁移、MCP 服务支持、AI 钩子
Version 6 变更：引入框架专属预设（React、Next.js、Vue、Svelte 等）

核心目标

1. 极速性能：借助 Biome 的 Rust 实现，实现即时的代码检查与格式化
2. 零配置设计：内置 200 多项适用于现代 TypeScript 开发的合理默认规则
3. 简洁与隐式运行：以最少的用户交互运行
4. 类型安全：强制启用 TypeScript 严格模式，并全面处理 null/undefined
5. 工具兼容性：与其他开发工具协同工作，不产生冲突

相较于其他方案的主要优势

相较于 ESLint + Prettier：

• 性能快 10–100 倍（Rust 对比 JavaScript）
• 一个工具取代两个工具
• 无需配置
• 默认在保存时自动修复
• 内置 TypeScript 严格模式

相较于单独使用 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）

特殊需求：

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

旧项目：

• 有自定义 ESLint 规则的大型代码库（需要投入迁移工作）
• 有大量 Prettier 自定义配置的项目

详细的限制和解决方法，请参阅：references/limitations-and-workarounds.md

交互式组件

此技能提供交互式命令和自主 Agent，简化工作流：

命令

• /ultracite:doctor - 验证项目设置，检查是否存在 v6→v7 预设路径问题，并检测冲突
• /ultracite:migrate - 交互式迁移向导（ESLint/Prettier → Ultracite，v6→v7 升级）

Agent

• 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   # Default
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"]
}

迁移步骤：

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

v7 新功能：

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

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

从 v5 升级到 v6

主要变更：引入了框架专属预设。

v5 方式（旧）：

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

v6 方式（新）：

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

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

项目适用性评估

调用此技能时，请扫描项目并进行评估：

1. 检查现有工具：

   # Check for ESLint
   ls -la .eslintrc* eslint.config.* package.json | grep eslint
   
   # Check for Prettier
   ls -la .prettierrc* prettier.config.* package.json | grep prettier
   
   # Check for Biome
   ls -la biome.json* package.json | grep biome
   

2. 识别框架：

   • 检查 package.json 中是否包含 react、next、vue、svelte 等
   • 推荐合适的预设

3. 评估项目规模：

   • 大型项目（1000+ 个文件）最能受益于 Rust 的性能
   • 小型项目可能感受不到速度差异

4. 检查 TypeScript 配置：

   • 如果存在 tsconfig.json，请注意 Ultracite 要求 strictNullChecks: true
   • 如果已禁用，请发出警告（这会产生大量警告）

5. 给出建议或警告：

   ✅ RECOMMENDED: This TypeScript + React project is ideal for Ultracite
   - 500+ files will benefit from Rust performance
   - React preset available
   - Can replace existing ESLint + Prettier setup
   
   ⚠️ CONSIDER: This project uses advanced ESLint plugins
   - Custom rule: eslint-plugin-custom-security
   - May need to retain ESLint for these specific rules
   - Could use Ultracite for formatting only
   

安装与设置

前提条件

• Node.js v20+
• 包管理器：Bun（首选）、npm、pnpm 或 yarn
• 项目根目录中有 package.json 文件

快速开始（交互式）

# Using Bun (preferred for speed)
bun x ultracite init

# With provider selection (v7+)
bun x ultracite init --linter biome   # Default, fastest
bun x ultracite init --linter eslint  # ESLint + Prettier + Stylelint
bun x ultracite init --linter oxlint  # Oxlint + Oxfmt (type-aware)

# Using npm
npx ultracite init

# Using pnpm
pnpm dlx ultracite init

# Using yarn
yarn dlx ultracite init

交互式设置将：

1. 提示选择提供程序（Biome、ESLint、Oxlint）——仅限 v7+
2. 安装 Ultracite 和提供程序依赖项
3. 提示选择框架（React、Next.js、Vue 等）
4. 询问编辑器设置（VS Code、Cursor 等）
5. 提供安装 AI Agent 规则（Cursor、Claude Code、Copilot）
6. 提示集成 Git 钩子（Husky、Lefthook、lint-staged）
7. 提供从现有工具（ESLint、Prettier）迁移的选项
8. 创建/合并配置文件（biome.jsonc、.eslintrc.js 等）
9. 更新 .vscode/settings.json 以集成编辑器
10. 在 tsconfig.json 中启用 strictNullChecks（如果使用 TypeScript）

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

# Auto-detect settings, skip prompts
bunx ultracite init --quiet

# Specify options explicitly (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. Install dependencies
bun add -D ultracite@7 @biomejs/biome@^2.0.0

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

# 3. Create VS Code settings
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. Enable TypeScript strict mode
# Add to tsconfig.json:
{
  "compilerOptions": {
    "strictNullChecks": true
  }
}

验证安装

# Check installation
bunx ultracite doctor

# Expected output:
# ✔ Biome is installed
# ✔ Configuration file found: biome.jsonc
# ✔ Editor integration configured
# ✔ TypeScript strict mode enabled

配置

基本配置

文件结构：

project-root/
├── biome.jsonc              # Main configuration
├── .vscode/settings.json    # VS Code integration
├── tsconfig.json            # TypeScript config (strictNullChecks required)
└── package.json

最小化 biome.jsonc：

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

  // Optional: Add framework preset
  // "extends": ["ultracite/core", "ultracite/react"],

  // Optional: Customize rules
  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "off"  // Disable specific rule
      }
    }
  },

  // Optional: Exclude files (Biome 2.x: use `includes` with `!` negation)
  "files": {
    "includes": ["**", "!dist", "!build", "!coverage", "!**/*.generated.ts"]
  }
}

框架预设

• ultracite/react：React Hooks、JSX a11y、组件最佳实践
• 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 预设包含 7 个类别的 200+ 条规则：

• 无障碍：ARIA 验证、语义化 HTML、键盘导航
• 正确性：类型安全、移除未使用的代码、全面检查依赖项
• 性能：代码优化、barrel 文件警告
• 安全性：防止使用 eval()、XSS 风险和不安全模式
• 风格：统一模式、优先使用 const、整理导入
• 可疑项：捕获宽松相等比较、debugger 语句和拼写错误
• 复杂度：认知复杂度限制

默认格式设置：2 个空格、每行 80 个字符、LF 换行符、单引号

有关详细的框架预设、规则说明和高级配置，请参阅：references/configuration-guide.md

用法

IDE 集成（推荐）

VS Code 设置：

1. 安装 Biome 扩展：biomejs.biome
2. 验证 .vscode/settings.json：

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

3. 禁用冲突的扩展（ESLint、Prettier）

功能：

• 保存时自动格式化
• 保存时自动修复（移除未使用的导入、修正顺序、应用严格相等比较）
• 粘贴时格式化
• 在问题面板中查看无法自动修复的问题
• 通过灯泡指示器快速修复

CLI 用法

检查代码（仅 lint）：

bunx ultracite check
bunx ultracite check src/
bunx ultracite check --diagnostic-level error  # Only errors

修复代码（自动修复）：

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 助手了解你的 lint 和格式化标准。

支持的编辑器：

• 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  # All editors
bunx ultracite generate-ai-rules --editor=cursor  # Specific editor

有关完整的 AI 编辑器集成指南和自定义方法，请参阅：references/ai-editor-integration.md

Monorepo 支持

Ultracite 针对 monorepo 进行了优化，支持：

• 共享基础配置
• 特定软件包的覆盖设置
• Turborepo/Nx 缓存集成
• 针对大型工作区的性能优化

monorepo 结构示例：

monorepo/
├── biome.json              # Shared base config
├── apps/
│   └── web/
│       └── biome.json      # Next.js-specific overrides
└── packages/
    └── ui/
        └── biome.json      # React-specific overrides

有关完整的 monorepo 设置、Turborepo/Nx 集成和性能建议，请参阅：references/monorepo-configuration.md

从 ESLint/Prettier/Biome 迁移

自动迁移：

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

手动迁移：

1. 分析当前配置
2. 将规则映射到 Biome 对应规则
3. 创建包含对应规则的 biome.json
4. 更新 package.json 脚本
5. 移除旧依赖
6. 彻底测试

有关包含详细规则映射的完整迁移指南，请参阅：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。

迁移脚本

ESLint/Prettier 迁移请参阅 scripts/migrate-to-ultracite.sh。

示例配置

请参阅 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：已知缺口和修复方法

软件包版本

当前版本（已于 2026-08-03 验证）：

• ultracite：最新版本
• @biomejs/biome：>=2.0.0

检查更新：

npm view ultracite version
npm view @biomejs/biome version

更新：

bun update ultracite @biomejs/biome

资源

官方文档：

• https://www.ultracite.ai/introduction
• https://www.ultracite.ai/setup
• https://www.ultracite.ai/configuration
• https://biomejs.dev/

示例：

• https://www.ultracite.ai/examples

故障排除：

• https://www.ultracite.ai/troubleshooting
• https://www.ultracite.ai/faq

社区：

• 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 插件配置
• 迁移到 Ultracite 的 ESLint 迁移
• 高级 CSS/SCSS 检查

references/provider-oxlint.md：当用户询问以下内容时：

• Oxlint 提供程序设置
• 类型感知检查功能
• Oxlint 的性能优势
• Oxlint 与 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 助手
• Model Context Protocol
• MCP 服务配置

references/ai-hooks.md：当用户询问以下内容时：

• AI hooks 设置（与 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：当用户询问以下内容时：

• Monorepo 设置
• 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 插件生态
• 文件类型支持
• 编辑器集成
• 迁移限制

安全安装

安装 linting/格式化软件包时，请遵循供应链安全最佳实践：

• 阻止安装后脚本 — npm config set ignore-scripts true（或 Bun：默认禁用）
• 冷却期 — 等待 7 天，让社区审查新的软件包版本
• 安装前审计 — 运行 socket package score npm <pkg>，或使用 socket npm install <pkg> 检查软件包

加载 dependency-upgrade 技能，获取完整的安全配置，包括 Socket CLI 集成、冷却期设置、锁文件验证和 CI 强制执行。

摘要

Ultracite 提供统一的 lint 和格式化解决方案，并支持多个提供方：

✅ 适用于：

• 启动新项目
• 使用 React/Next/Vue/Svelte 构建
• 在 monorepo 中工作
• 希望无需配置即可保持格式一致
• 性能至关重要（Biome/Oxlint 提供方）
• 需要兼容 ESLint（ESLint 提供方）
• 使用 AI 编码助手
• 需要类型感知 lint（Oxlint）

⚠️ 以下情况可考虑其他方案：

• 需要任何提供方都不支持的特定 ESLint 插件
• 需要高级 CSS lint（不过 ESLint 提供方包含 Stylelint）
• 需要支持旧版框架

主要优势：

• 多提供方：可选择 Biome（最快）、ESLint（兼容性最佳）或 Oxlint（类型感知）
• 版本 7：预设路径迁移、MCP 服务、AI 钩子、多提供方架构
• 版本 6：框架专用预设（React、Next.js、Vue、Svelte 等）
• 速度比传统的 ESLint + Prettier 快 10-100 倍（Biome/Oxlint）
• 零配置（Biome 预配置了 200 多条规则）
• 框架专用预设
• AI 编辑器集成 + AI 钩子
• Git 钩子支持
• 强制启用 TypeScript strict 模式

安装：

bun x ultracite init --linter biome   # Default (v7+)
bun x ultracite init --linter eslint  # ESLint provider (v7+)
bun x ultracite init --linter oxlint  # Oxlint provider (v7+)

最常见的工作流：

1. 使用 bun x ultracite init 安装
2. 选择框架预设（React、Next.js 等）
3. 选择 Git 钩子集成（Husky、Lefthook、lint-staged）
4. 启用 AI 编辑器规则（Cursor、Claude Code、Copilot）
5. 可选：从 ESLint/Prettier 迁移
6. 编写代码并在保存时自动格式化
7. 提交代码，由 pre-commit 钩子确保质量

请记住：

• 安装前务必检查是否已有 Git 钩子管理工具
• 评估项目适用性（扫描 ESLint/Prettier/框架）
• 根据项目特征提出建议或警告
• 在 TypeScript 项目中启用 strictNullChecks
• 使用框架专用预设以获得最佳效果
• 根据用户问题按需加载参考文件