---
url: /docs/adr/005-oxlint-oxfmt.md
---
# 决策 005：静态检查与格式化

**状态：** 已采纳。**日期：** 2026-09-11。

## 问题

旧检查工具依赖 TypeScript 编程接口，与原生编译器迁移产生冲突；静态检查和格式化也需要统一、可快速运行的基线。

## 决策

Oxlint 替代原静态检查工具，配置在 `.oxlintrc.json`；Oxfmt 负责格式化，配置在 `.oxfmtrc.json`。根目录提供 `bun lint`、`bun format` 和 `bun format:check`。

保留 `lint-staged` 检查暂存内容，避免部分暂存时检查与真正提交的版本不同。未匹配到支持文件时不应无故使提交失败。

## 规则范围

基线侧重正确性，补充 React Hooks、明确类型、注释约束和模块导入规则；不把旧工具全部规则机械移植。无用变量等由检查发现，格式由格式化器统一。

部分旧 React 规则没有对应覆盖，需要审查事件监听、计时器和观察器是否正确释放，以及生成组件是否遵循项目规范。

## 模板与文档边界

Astro 模板使用 `bun web:check` 和编辑器支持，不假定普通静态检查能验证所有标记。Markdown 段落保持单行；VitePress 提示容器的开始和结束标记与内容之间留空行，防止格式化破坏渲染。

不手动按编辑器喜好重排导入，统一使用格式化器，见 [导入顺序](./007-oxfmt-sorts-imports.md)。