Oxc 配置指南：用 oxlint + oxfmt 替代 ESLint + Prettier

使用 Oxidation Compiler 工具链：oxlint（代码检查）+ oxfmt（代码格式化）。

---

文件结构

文件	工具	用途
.oxlintrc.json	oxlint	代码检查规则配置
.oxfmtrc.json	oxfmt	格式化配置

---

一、oxlint — 代码检查

命令

oxlint                     # 默认检查（error 阻断，warn 提醒）
oxlint --deny-warnings     # warn 也视为 error（CI 推荐）
oxlint --fix               # 自动修复可修复问题

配置方式

oxlint v1.x 不推荐逐条罗列规则，而是用 categories 分类批量启用：

分类	等级	说明
correctness	error	代码明显错误 — 阻断
suspicious	warn	大概率有问题 — 提醒
perf	warn	性能相关 — 提醒
style	未启用	由 oxfmt 格式化处理，不重复检查
pedantic / restriction / nursery	未启用	过于严格或实验性规则

好处： 不绑定具体规则名，升级 oxlint 不会因规则改名而报错。

配置结构 .oxlintrc.json

plugins

插件	说明
vue	Vue 2 模板编译检查
unicorn	现代 JS 最佳实践
oxc	oxc 特有正确性规则

categories.correctness 会自动启用 eslint 和 import 插件的相关规则，无需显式声明。

env

{ "builtin": true }

builtin 等价于 browser + es2020 + node 三者之和，更简洁。

globals — UniApp 全局变量

声明为 readonly，避免误报 no-undef：

变量	平台
uni、getApp、getCurrentPages、__uniConfig	UniApp 通用
Vue	Vue 框架
wx	微信小程序
tt	头条小程序
my	支付宝小程序
swan	百度小程序
plus	5+ App
App、Page、Component、Behavior	小程序构造器

settings.vue.version

"2"  // Vue 2 模式。升级 Vue 3 后改为 "3"

rules — 自定义覆盖

categories 兜底了大多数规则，此处只保留项目特有的覆盖项：

规则	等级	说明
no-console	warn	不建议 console.log 留生产代码
no-debugger	warn	debugger 不应留生产代码
prefer-const	warn	未重新赋值的变量用 const
no-var	warn	用 let/const 代替 var
eqeqeq	warn	必须 ===/!==，不用 ==/!=
no-empty	warn	空代码块（允许 catch 为空）
unicorn/throw-new-error	warn	throw Error() → throw new Error()
vue/no-side-effects-in-computed-properties	warn	计算属性中不能有副作用

不带前缀的规则名（如 no-console）由 oxlint 自动匹配对应插件。

ignorePatterns

["node_modules/", "unpackage/", "uni_modules/", "dist/", "*.min.js"]

---

二、oxfmt — 代码格式化

命令

oxfmt                    # 格式化并覆写文件（默认 --write）
oxfmt --check            # 仅检查，不覆写（CI 用）
oxfmt --list-different   # 列出将被修改的文件
oxfmt PATH               # 指定文件/目录

配置结构 .oxfmtrc.json

配置项	值	说明
arrowParens	"always"	箭头函数参数始终加括号 (x) => x
bracketSameLine	true	JSX 右尖括号与最后一行属性同行
bracketSpacing	true	对象大括号内留空格 { foo: 1 }
endOfLine	"lf"	换行符使用 LF
embeddedLanguageFormatting	"auto"	自动格式化嵌入代码
htmlWhitespaceSensitivity	"ignore"	HTML 空白不敏感
jsxSingleQuote	true	JSX 中使用单引号
printWidth	120	每行最多 120 字符
quoteProps	"as-needed"	对象属性名只在必要时加引号
semi	false	行尾不加分号
singleQuote	true	字符串使用单引号
tabWidth	2	缩进 2 空格
trailingComma	"es5"	尾部逗号（对象/数组加，函数参数不加）
useTabs	false	用空格缩进
vueIndentScriptAndStyle	false	Vue 文件中 <script>/<style> 不额外缩进
sortPackageJson	false	不自动排序 package.json 字段

---

三、使用方式

本地开发

cd mobile
npm install                  # 安装 oxlint + oxfmt

npm run lint                 # oxlint 代码检查
npm run lint:fix             # oxlint 检查 + 自动修复
npm run format               # oxfmt 格式化全部文件
npm run format:check         # oxfmt 仅检查格式

修改格式化配置

直接编辑 .oxfmtrc.json，修改后立即生效。

Husky + lint-staged（可选）

提交前自动对暂存文件运行 oxlint 检查和 oxfmt 格式化，把住最后一道关：

npm install -D husky lint-staged
npx husky init

修改 .husky/pre-commit：

npx lint-staged

package.json 中添加：

{
  "lint-staged": {
    "*.{js,ts,vue}": ["oxlint --fix", "oxfmt"],
    "*.{css,scss,json,md}": ["oxfmt"]
  }
}

oxfmt 默认 --write，无需额外参数。先格式化再 lint 检查，确保两者都通过。

跳过 hook（紧急情况）：git commit --no-verify -m "紧急修复"

CI 集成

- run: npm ci
- run: npm run lint
- run: npm run format:check

---

四、常见问题

Q: oxlint 报错但代码实际没问题？
A: 可能是 UniApp 特有的全局变量未声明。在 .oxlintrc.json 的 globals 中添加即可。

Q: oxfmt 和 oxlint 规则冲突？
A: 使用 categories 方式时，style 类规则默认不启用，格式相关检查由 oxfmt 全权处理，不会冲突。

Q: 只想检查部分目录？
A: oxlint pages/ --deny-warnings 或 oxfmt pages/ --check

---

五、工具版本

oxlint --version   # 1.74.0
oxfmt --version    # 0.59.0

更新：npm update oxlint oxfmt