Ultracite：为 AI 时代打造的零配置代码规范工具

作者 JinSo

2025年11月22日 18:26

Ultracite 是什么？

Ultracite 是一个高度固定化、零配置的代码检查和格式化工具。它基于高性能的 Biome 构建，适用于所有前端项目，无论你使用 React、Vue、Angular 还是原生 JavaScript，都能让你和 AI 编程助手编写出一致且高质量的代码。

核心理念：约定优于配置

不同于 ESLint + Prettier 需要大量配置，Ultracite 采用了极简主义设计理念：

零配置：开箱即用，无需编写任何配置文件
固定规则：精心挑选的规则集，避免无谓的选择困扰
统一标准：整个团队和 AI 助手都遵循相同的代码规范

快速开始

初始化

# 在项目中初始化 Ultracite
pnpm dlx ultracite init

Ultracite 提供了交互式的安装体验，让你根据项目需求选择功能：

❯ pnpm dlx ultracite init
┌
888     888 888    88888888888 8888888b.         d8888  .d8888b. 8888888 88888888888 8888888888
888     888 888        888     888   Y88b       d88888 d88P  Y88b  888       888     888
888     888 888        888     888    888      d88P888 888    888  888       888     888
888     888 888        888     888   d88P     d88P 888 888         888       888     8888888
888     888 888        888     8888888P"     d88P  888 888         888       888     888
888     888 888        888     888 T88b     d88P   888 888    888  888       888     888
Y88b. .d88P 888        888     888  T88b   d8888888888 Y88b  d88P  888       888     888
 "Y88888P"  88888888   888     888   T88b d88P     888  "Y8888P" 8888888     888     8888888888

│
●  Detected lockfile, using pnpm
│
◇  Remove existing formatters/linters (recommended for clean migration)?
│  Remove ESLint (dependencies, config files, VS Code settings)
│
◇  Which frameworks are you using (optional)?
│  React
│
◇  Which editors do you want to configure (recommended)?
│  VSCode / Cursor / Windsurf
│
◇  Which agents do you want to enable (optional)?
│  Cursor
│
◇  Which agent hooks do you want to enable (optional)?
│  Cursor
│
◇  Would you like any of the following (optional)?
│  Husky pre-commit hook, Lefthook pre-commit hook, Lint-staged
│
◑  ...省略安装步骤
◆  Successfully initialized Ultracite configuration!

初始化完成后，Ultracite 会根据你的选择自动完成以下配置：

安装必要的依赖包
生成编辑器配置文件
创建 AI 代码规范提示词（这是 Ultracite 的核心特性之一）
配置 Git Hooks 工具（Husky、Lefthook、Lint-staged）
更新 package.json 脚本
生成 biome.json 配置文件

关于 Git Hooks 工具的详细介绍，可以参考我之前的文章：在 Monorepo 中对代码进行规范(husky + lint-staged)

基本使用

# 检查代码问题
npx ultracite check

# 自动修复和格式化代码
npx ultracite fix

AI 友好特性

这是 Ultracite 的一大亮点 —— 它专门为 AI 编程时代设计，让 AI 助手也能遵循项目的代码规范。

AI 提示词集成

当你选择启用 AI agent（如 Cursor）时，Ultracite 会生成一份详细的代码规范提示词文件 .cursor/rules/ultracite.mdc。这份文件包含了完整的编码规范，涵盖：

类型安全规范：要求使用明确的类型定义，避免 any 类型
现代语法规范：优先使用箭头函数、可选链、解构赋值等现代特性
异步编程规范：正确使用 async/await，妥善处理错误
React 最佳实践：函数组件、Hooks 规则、无障碍访问等
代码组织原则：函数复杂度控制、早期返回、关注点分离

有了这份提示词，AI 助手生成的代码会自动遵循这些规范，大大减少了代码审查的工作量。

Cursor Hooks 集成

对于 Cursor 用户，Ultracite 还会生成 hooks 配置（.cursor/hooks.json）：

{
  "version": 1,
  "hooks": {
    "afterFileEdit": [
      {
        "command": "npx ultracite fix"
      }
    ]
  }
}

这个配置实现了"保存即格式化"的效果 —— 每次你或 AI 编辑文件后，代码都会自动格式化，保持整个项目的一致性。

Git Hooks 集成

Ultracite 支持主流的 Git Hooks 工具，确保提交的代码都经过检查和格式化。

Husky 集成

生成的 .husky/pre-commit 文件会在提交前自动运行代码检查：

#!/bin/sh
# Exit on any error
set -e

# Check if there are any staged files
if [ -z "$(git diff --cached --name-only)" ]; then
  echo "No staged files to format"
  exit 0
fi

# Store the hash of staged changes to detect modifications
STAGED_HASH=$(git diff --cached | sha256sum | cut -d' ' -f1)

# Save list of staged files (handling all file states)
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACMR)
PARTIALLY_STAGED=$(git diff --name-only)

# Stash unstaged changes to preserve working directory
git stash push --quiet --keep-index --message "pre-commit-stash" || true
STASHED=$?

# Run formatter on the staged files
pnpm dlx ultracite fix
FORMAT_EXIT_CODE=$?

# Restore working directory state
if [ $STASHED -eq 0 ]; then
  # Re-stage the formatted files
  if [ -n "$STAGED_FILES" ]; then
    echo "$STAGED_FILES" | while IFS= read -r file; do
      if [ -f "$file" ]; then
        git add "$file"
      fi
    done
  fi

  # Restore unstaged changes
  git stash pop --quiet || true
fi

# Check if staged files actually changed
NEW_STAGED_HASH=$(git diff --cached | sha256sum | cut -d' ' -f1)
if [ "$STAGED_HASH" != "$NEW_STAGED_HASH" ]; then
  echo "✨ Files formatted by Ultracite"
fi

exit $FORMAT_EXIT_CODE

这个脚本会智能处理部分暂存的文件，确保只格式化你要提交的代码。

Lefthook 集成

如果你选择使用 Lefthook，会生成 lefthook.yml 配置：

pre-commit:
  jobs:
    - run: pnpm dlx ultracite fix
      glob:
        - "*.js"
        - "*.jsx"
        - "*.ts"
        - "*.tsx"
        - "*.json"
        - "*.jsonc"
        - "*.css"
      stage_fixed: true

Lefthook 的优势在于并行执行和更灵活的配置选项。

Lint-staged 集成

配合 lint-staged 可以只处理暂存的文件，在 package.json 中会添加：

"lint-staged": {
  "*.{js,jsx,ts,tsx,json,jsonc,css,scss,md,mdx}": [
    "pnpm dlx ultracite fix"
  ]
}

VSCode 深度集成

Ultracite 会自动为 VSCode（包括 Cursor、Windsurf）生成配置，实现保存时自动格式化：

// .vscode/settings.json
{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[javascriptreact]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[json]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[jsonc]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[css]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[graphql]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "editor.formatOnSave": true,
  "editor.formatOnPaste": true,
  "emmet.showExpandedAbbreviation": "never",
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}

MCP（Model Context Protocol）支持

MCP 是一个开放标准，让 Claude、Cursor 等 AI 工具能够安全地连接外部数据源和系统。可以把它理解为一个"万能遥控器"，让 AI 工具能够访问真实世界的数据和功能。Ultracite 通过支持 MCP 来增强你的 AI 开发工作流。

安装配置

选择你的 AI 工具

确保你使用的 AI 开发工具支持 MCP：
- Claude Desktop（免费，推荐初学者使用）
- Cursor（AI 驱动的代码编辑器）
- Windsurf by Codeium（AI 开发平台）
- 其他支持 MCP 的工具
找到配置文件位置

根据你的 AI 工具，需要编辑对应的配置文件：
- Claude Desktop:
  - macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
  - Windows: %APPDATA%\Claude\claude_desktop_config.json
- Cursor: .cursor/mcp.json
- Windsurf: .codeium/windsurf/mcp_config.json
- 其他工具: 查看对应工具的 MCP 文档

添加 Ultracite 配置

将以下配置复制到你的 MCP 配置文件中：

{
  "mcpServers": {
    "ultracite": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<https://www.ultracite.ai/api/mcp/mcp>"
      ]
    }
  }
}

重启 AI 工具

关闭并重新打开你的 AI 应用，让配置生效。
验证连接

通过询问你的 AI 助手来测试集成是否成功：

"Ultracite 有哪些可用的规则？"

如果配置成功，AI 应该能够列出并解释 Ultracite 的规则！

从 ESLint + Prettier 迁移

迁移过程非常简单：

运行 pnpm dlx ultracite init
选择移除现有的 ESLint 和 Prettier 配置
更新 package.json 中的脚本命令
删除旧的配置文件

Ultracite 的规则集已经涵盖了大多数常用的 ESLint 和 Prettier 规则，你几乎不需要任何额外配置。

总结

Ultracite 代表了代码质量工具的新方向：简单、快速、AI 友好。它特别适合：

使用 AI 编程的开发者：通过提示词和 hooks 确保 AI 生成高质量代码
追求效率的团队：零配置设计，减少工具链维护成本
任何前端项目：无论使用什么框架，都能获得一致的代码质量
Monorepo 项目：原生支持，配置简单

相比传统的 ESLint + Prettier 组合，Ultracite 提供了更快的性能、更简单的配置、更统一的工具链，以及原生的 AI 编程支持。在 AI 辅助编程越来越普及的今天，选择一个 AI 友好的代码规范工具，能让你的开发效率更上一层楼。

普通视图