在 JS/TS 项目需要快速零配置 lint/格式化…

适用于新建或迁移中的 JavaScript/TypeScript 项目（React/Next/Vue/Svelte/monorepo），希望用 Biome/ESLint/Oxlint 提供商实现零配置 lint、格式化、类型安全和 AI 编辑器集成。

适用场景

解决思路

1. 运行 `ls -la .eslintrc* eslint.config.* package.json | grep eslint` 检查现有 ESLint，`ls -la .prettierrc* prettier.config.* package.json | grep prettier` 检查 Prettier，`ls -la biome.json* package.json | grep biome` 检查 Biome。
2. 在 `package.json` 中识别框架（如 react、next、vue、svelte 等），据此选择对应框架 preset。
3. 评估项目规模：1000+ 文件的大型项目最能受益于 Rust 性能；小项目可能感觉不到速度差异。
4. 检查 `tsconfig.json`；若存在，确保 `strictNullChecks: true`，否则会生成大量警告。
5. 根据评估结果给出推荐或警告：例如推荐 TypeScript+React 项目；若使用高级 ESLint 插件，考虑仅用 Ultracite 做格式化或保留 ESLint 并行运行。
6. 使用交互式快速开始：`bun x ultracite init`（首选），或 `npx ultracite init`、`pnpm dlx ultracite init`、`yarn dlx ultracite init`。
7. 选择 provider：`bun x ultracite init --linter biome`（默认，最快）、`bun x ultracite init --linter eslint`（ESLint+Prettier+Stylelint）、`bun x ultracite init --linter oxlint`（Oxlint+Oxfmt，类型感知）。
8. 选择 provider 依据：Biome 默认推荐大多数项目；ESLint+Prettier+Stylelint 推荐最大兼容；Oxlint+Oxfmt 推荐最大速度和类型感知的大 TypeScript 代码库。
9. 在交互式设置中依次完成：选择 provider、安装 Ultracite 和 provider 依赖、选择框架、选择编辑器、安装 AI agent rules、选择 Git hook 集成、迁移现有工具、创建/合并配置文件、更新 `.vscode/settings.json`、在 TypeScript 中启用 `strictNullChecks`。
10. 非交互式 CI/自动化：运行 `bunx ultracite init --quiet`，或显式指定：`bunx ultracite init --linter biome --pm bun --frameworks react,next --editors vscode --agents cursor,claude --integrations husky --migrate eslint,prettier --quiet`。
11. 手动安装依赖：`bun add -D ultracite@7 @biomejs/biome@^2.0.0`。
12. 手动创建 `biome.jsonc`：`{ "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json", "extends": ["ultracite/core"] }`。
13. 手动创建 `.vscode/settings.json`：设置 `editor.defaultFormatter` 为 `biomejs.biome`，`editor.formatOnSave` 为 `true`，`editor.codeActionsOnSave` 中 `quickfix.biome` 和 `source.organizeImports.biome` 为 `explicit`。
14. 在 `tsconfig.json` 的 `compilerOptions` 中设置 `"strictNullChecks": true`。
15. 验证安装：运行 `bunx ultracite doctor`，期望检查 Biome 已安装、配置文件找到、编辑器集成已配置、TypeScript strict mode 已启用。
16. 配置基本 `biome.jsonc`：设置 `$schema` 和 `extends`；可选自定义规则，如 `linter.rules.suspicious.noConsoleLog: "off"`；可选排除文件，Biome 2.x 用 `files.includes: ["**", "!dist", "!build", "!coverage", "!**/*.generated.ts"]`。
17. 添加框架 preset：在 `extends` 中加入 `"ultracite/react"`、`"ultracite/nextjs"`、`"ultracite/vue"`、`"ultracite/svelte"` 等。
18. 了解 `ultracite/core` 包含 200+ 规则，覆盖 accessibility、correctness、performance、security、style、suspicious、complexity；格式化默认 2 空格、80 字符/行、LF、单引号。
19. IDE 集成：安装 Biome 扩展 `biomejs.biome`，验证 `.vscode/settings.json`，禁用冲突的 ESLint、Prettier 扩展。
20. CLI 使用：`bunx ultracite check`、`bunx ultracite check src/`、`bunx ultracite check --diagnostic-level error`；自动修复用 `bunx ultracite check --write`；仅格式化用 `bunx ultracite format --write`。
21. 在 `package.json` scripts 中添加：`"lint": "ultracite check"`、`"lint:fix": "ultracite check --write"`、`"format": "ultracite format --write"`。
22. Git hooks 集成：运行 `bunx ultracite init --integrations husky`、`bunx ultracite init --integrations lefthook` 或 `bunx ultracite init --integrations lint-staged`。
23. 在 `.husky/pre-commit` 中写入：`ultracite check --staged --write`。
24. 生成 AI 编辑器规则：运行 `bunx ultracite generate-ai-rules`、`bunx ultracite generate-ai-rules --all` 或 `bunx ultracite generate-ai-rules --editor=cursor`；支持 Cursor、Claude Code、GitHub Copilot、Continue.dev、Codeium、Zed。
25. Monorepo 支持：在根目录使用共享 base 配置（如 `biome.json`），各 app/package 用 `biome.json` 覆盖；结合 Turborepo/Nx 缓存。
26. 自动迁移：运行 `bunx ultracite migrate eslint`、`bunx ultracite migrate prettier` 或 `bunx ultracite migrate biome`。
27. 手动迁移步骤：分析当前配置、映射规则到 Biome 等价物、创建 `biome.json`、更新 `package.json` scripts、移除旧依赖、彻底测试。
28. v6→v7 迁移：运行 `bun update ultracite` 更新包；在 `biome.jsonc` 中更新 preset 路径，添加 `/biome/` 段（如 `"ultracite/core"` → `"ultracite/biome/core"`）；运行 `npx ultracite doctor` 验证；运行 `npx ultracite check .` 测试。
29. v5→v6 迁移：在 `extends` 中加入框架 preset（如 `"ultracite/react"`）。
30. 已知限制的 workaround：CSS/SCSS 用 Stylelint；Angular/Astro 用 `ultracite/core` + 手动规则；无 Biome 等价的特定 ESLint 插件与 Ultracite 并行运行 ESLint；Markdown/YAML/HTML 用 markdownlint/yamllint/htmlhint。
31. 故障排除：VS Code 不格式化则安装 Biome 扩展并配置；ESLint 冲突则禁用 ESLint 或选择性运行；解析错误则配置 JSX 支持；pre-commit 失败则用 `bunx` 而不是全局安装；CI 失败则固定 Bun/Node 版本并增加内存限制。
32. 安全安装：运行 `npm config set ignore-scripts true`（Bun 默认禁用）；等待 7 天让新版本被社区审查；安装前运行 `socket package score npm <pkg>` 或使用 `socket npm install <pkg>` 审计。
33. 使用交互式命令：`/ultracite:doctor` 验证项目设置、检查 v6→v7 preset 路径、检测冲突；`/ultracite:migrate` 运行迁移向导。
34. 使用 agent：`config-validator` 分析 `biome.jsonc` 的语法、preset 路径、规则冲突和性能；`migration-assistant` 指导 ESLint/Prettier 迁移并进行规则映射和差距分析。
35. v7 支持 MCP server 集成和 AI hooks（AI 编辑后自动格式化）；需要时加载 `references/mcp-integration.md` 和 `references/ai-hooks.md`。
36. 按需加载参考文件：根据问题加载 `references/provider-biome.md`、`references/provider-eslint.md`、`references/provider-oxlint.md`、`references/v6-migration.md`、`references/v7-migration.md`、`references/configuration-guide.md`、`references/git-hooks-setup.md`、`references/ai-editor-integration.md`、`references/monorepo-configuration.md`、`references/migration-guides.md`、`references/troubleshooting.md`、`references/limitations-and-workarounds.md`。
37. 可使用模板脚本：`scripts/install-ultracite.sh` 自动化初始设置，`scripts/migrate-to-ultracite.sh` 进行 ESLint/Prettier 迁移。
38. 检查更新：运行 `npm view ultracite version` 和 `npm view @biomejs/biome version`；更新用 `bun update ultracite @biomejs/biome`。

适用边界 · 注意事项

• 需要特定 ESLint 插件（Biome/Oxlint 无等价）或大量自定义 ESLint/Prettier 配置的遗留大型项目。
• 需要高级 CSS/SCSS lint、CSS 属性排序，或 Markdown/YAML/HTML linting。
• 需要 Angular/Ember 等框架专用规则，Biome 支持基础或有限。