Formula Lint

一句话：Formula Lint 让你在几分钟内给任何项目加上统一的代码规范。

npm install -g formula-lint
formula init
formula lint

快速开始

1. 安装（30秒）

npm install -g formula-lint

2. 初始化项目（1分钟）

在你的项目根目录运行：

formula init

这会：

• 创建 eslint.config.js 配置文件
• 配置 VSCode 自动修复（如果有 .vscode 目录）
• 在 package.json 添加 lint 脚本

3. 运行检测（即刻）

formula lint

任务指南

我要在新项目启用代码规范

cd 你的项目
formula init

如果项目已有 ESLint 配置：

formula init --force    # 覆盖现有配置

生成的配置文件（eslint.config.js）：

import formula from '@formula/lint-config'

export default formula({
  react: true,        // React 项目设为 true
  typescript: true,   // TypeScript 项目设为 true
  formatters: true,   // 启用格式化
})

我要检测代码

检测整个项目：

formula lint

只检测特定目录：

formula lint src/
formula lint src/components/

只检测特定文件：

formula lint src/index.ts src/utils.ts

不同的输出格式：

formula lint                    # 默认格式，适合阅读
formula lint --format compact   # 紧凑格式，适合大量文件
formula lint --format json      # JSON 格式，适合程序解析

我要自动修复问题

修复所有能自动修复的问题：

formula lint --fix

常见自动修复项：

• 多余空格、换行
• 分号缺失/多余
• 引号统一
• 缩进对齐

注意： 不是所有问题都能自动修复，剩余问题需要手动修改。

我要集成到 CI/CD

GitHub Actions 示例：

name: Lint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g formula-lint
      - run: formula lint

设置警告上限（超过则失败）：

formula lint --max-warnings 10

生成 JSON 报告：

formula lint --format json > eslint-report.json

我要在保存时自动修复

运行 formula init 时已自动配置 .vscode/settings.json：

{
  "eslint.useFlatConfig": true,
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

如果未生效：

1. 确认已安装 VSCode ESLint 插件
2. 重启 VSCode

我要自定义规则

编辑项目根目录的 eslint.config.js：

import formula from '@formula/lint-config'

export default formula({
  react: true,
  typescript: true,
  formatters: true,

  // 忽略特定文件/目录
  ignores: [
    'legacy/**',
    '*.config.js',
  ],

  // 自定义规则
  rules: {
    'no-console': 'off',           // 允许 console
    'react/prop-types': 'off',     // 关闭 prop-types 检查
  },
})

我要查看详细日志

排查问题时使用：

formula lint --verbose      # 显示检测的文件和配置路径
formula init --verbose      # 显示初始化详细过程

命令参考

| 命令 | 用途 | 常用选项 | |------|------|---------| | formula init | 初始化项目配置 | --force 覆盖现有配置 | | formula lint [files...] | 运行代码检测 | --fix 自动修复--format <format> 输出格式--max-warnings <n> 警告上限 |

配置选项

formula({
  // 技术栈
  react: false,       // 启用 React 规则
  typescript: true,   // 启用 TypeScript

  // 格式化
  formatters: true,   // 启用 Prettier 格式化

  // 忽略
  ignores: [],        // 额外忽略路径

  // 规则覆盖
  rules: {},          // 自定义 ESLint 规则
})

故障排查

检测到正确的文件，但规则不对

确认 eslint.config.js 存在且配置正确。Formula Lint 会优先使用项目配置。

init 后 VSCode 不自动修复

1. 安装 ESLint 插件
2. 确认 .vscode/settings.json 存在且包含 source.fixAll.eslint
3. 重启 VSCode

检测太慢

Formula Lint 已启用缓存。首次检测较慢，后续会快很多。 如需清除缓存：

rm .eslintcache

环境要求

• Node.js >= 18.0.0

许可证

MIT