Lint 与格式化

概览

本项目采用 Oxc 工具链 作为核心 lint 与格式化方案：

职责	工具	版本	配置文件
代码检查 (Lint)	Oxlint	`^1.60.0`	`.oxlintrc.json`
代码格式化 (Format)	Oxfmt	`^0.45.0`	`.oxfmtrc.json`
编辑器基础规范	EditorConfig	—	`.editorconfig`
任务编排	Turborepo	—	`turbo.json`

Expo 移动端应用 (apps/app、apps/native-ui-playground) 仍使用 ESLint + eslint-config-expo，其余所有 Web 端包均已迁移至 Oxlint。

常用命令

# 全仓库 lint（通过 Turborepo 并行执行各包的 lint 脚本）
pnpm lint

# 全仓库格式化
pnpm format

# 仅检查格式（不写入，适合 CI）
pnpm format:check

Oxlint — 代码检查

工具选型理由

Oxlint 使用 Rust 编写，相较 ESLint 有 50-100 倍 的性能优势，且无需安装额外的 parser。项目通过 .oxlintrc.json 进行配置，支持根级配置继承 + 子包 override 的分层模式。

配置层级

.oxlintrc.json                        ← 根配置（所有包共享）
├── apps/admin/.oxlintrc.json          ← Admin 应用（+ React / Sort 插件）
├── apps/core-docs/.oxlintrc.json      ← 核心文档站（+ Next.js / a11y 插件）
├── apps/project-docs/.oxlintrc.json   ← 项目文档站（+ Next.js / JSDoc 插件）
├── packages/web/ui/antd/.oxlintrc.json
├── packages/web/ui/compose/.oxlintrc.json
└── packages/web/ui/primitives/.oxlintrc.json

根配置插件

根 .oxlintrc.json 启用的插件：

node — Node.js 环境规则（node/handle-callback-err、node/no-path-concat 等）
import — 导入规范（禁止重复导入、禁止可变导出等）
unicorn — 现代 JS 最佳实践（prefer-node-protocol、throw-new-error 等）
typescript（通过 overrides 对 *.ts / *.tsx 启用）— 类型安全规则

子包扩展插件

Admin 应用与 UI 组件包在根配置基础上额外启用：

react — React 规则（rules-of-hooks、exhaustive-deps、jsx-key 等）
eslint-plugin-sort（通过 jsPlugins 桥接）— 排序规则
- sort/destructuring-properties — 解构属性排序
- sort/import-members — import 成员排序
- sort/exports — export 排序
- sort/string-enums / sort/string-unions — 枚举/联合类型成员排序
- sort/type-properties — 类型属性排序

文档站点额外启用：

nextjs — Next.js 框架规则
jsx-a11y — 无障碍规则（仅 core-docs）
jsdoc / promise — JSDoc 注释与 Promise 使用规范（仅 project-docs）

核心规则亮点

规则	级别	说明
`eqeqeq`	error	强制全等比较
`no-console`	warn	禁止 console（scripts 目录豁免）
`no-unused-vars`	error	禁止未使用变量（`_` 前缀豁免）
`prefer-const`	error	未重新赋值必须用 `const`
`no-var`	error	禁止 `var`
`typescript/consistent-type-imports`	error	强制使用 `type` 导入
`typescript/no-explicit-any`	off	允许 `any`（不作硬性限制）
`complexity`	error	限制圈复杂度
`max-depth` / `max-params`	error	限制嵌套深度与参数数量

各包 lint 脚本

包	`lint` 脚本
根 (`package.json`)	`turbo run lint`
`apps/admin`	`oxlint --fix`
`apps/core-docs`	`oxlint`
`apps/project-docs`	`oxlint`
`packages/web/ui/*`	`oxlint --fix`
`apps/app`	`expo lint`（ESLint）
`apps/native-ui-playground`	`expo lint`（ESLint）

Oxfmt — 代码格式化

工具选型理由

Oxfmt 是 Oxc 工具链的格式化器，同样基于 Rust，性能极高。项目使用它替代了 Prettier，配置文件为根目录的 .oxfmtrc.json，全仓库共享一份配置。

格式化规则

根据 .oxfmtrc.json 的配置：

{
  "printWidth": 120,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "none",
  "bracketSpacing": true,
  "bracketSameLine": false,
  "arrowParens": "avoid",
  "endOfLine": "lf",
  "singleAttributePerLine": false,
  "jsdoc": true,
  "sortImports": {
    "partitionByNewline": true,
    "newlinesBetween": false
  },
  "sortPackageJson": true
}

规则说明

配置项	值	说明
`printWidth`	`120`	每行最大字符数
`semi`	`true`	语句末尾加分号
`singleQuote`	`true`	使用单引号
`trailingComma`	`"none"`	不添加尾随逗号
`arrowParens`	`"avoid"`	箭头函数单参数不加括号
`endOfLine`	`"lf"`	统一使用 LF 换行符
`jsdoc`	`true`	格式化 JSDoc 注释
`sortImports`	`{ partitionByNewline: true }`	自动排序 import 语句
`sortPackageJson`	`true`	自动排序 `package.json` 字段

忽略文件

格式化会跳过以下目录/文件：

node_modules、dist、.turbo、.next、.cache、coverage
pnpm-lock.yaml、routeTree.gen.ts
.claude、.agents

EditorConfig

.editorconfig 确保不同编辑器之间的基础格式一致：

[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
trim_trailing_whitespace = true
insert_final_newline = true
quote_type = single

[*.md]
trim_trailing_whitespace = false

Turborepo 集成

turbo.json 中定义了 lint 任务：

{
  "lint": {
    "dependsOn": ["^build"],
    "outputs": []
  }
}

dependsOn: ["^build"] — lint 任务会等待依赖包构建完成后再执行，确保类型信息可用
outputs: [] — lint 不产生文件输出，不做缓存

格式化 (format / format:check) 直接在根 package.json 调用 oxfmt，不经过 Turborepo，因为 Oxfmt 天然支持全仓库扫描。

工具链架构图

pnpm lint
  └─ turbo run lint
       ├─ apps/admin        → oxlint --fix
       ├─ apps/core-docs    → oxlint
       ├─ apps/project-docs → oxlint
       ├─ packages/web/ui/* → oxlint --fix
       ├─ apps/app          → expo lint (ESLint)
       └─ apps/native-ui-playground → expo lint (ESLint)

pnpm format
  └─ oxfmt (全仓库, .oxfmtrc.json)

pnpm format:check
  └─ oxfmt --check (CI 模式, 仅检查不写入)

添加新包时的 Lint 配置

在新包的 package.json 中添加 "lint": "oxlint" 或 "lint": "oxlint --fix" 脚本
如果新包有特殊需求（如 React、Next.js 规则），在包目录下创建 .oxlintrc.json 覆盖/扩展根配置
Turborepo 会自动发现并编排所有包含 lint 脚本的包

Lint 与格式化

On this page