在前端工程化的道路上，我们总是在追求极致的代码规范。无论是 ESLint 的代码风格检查，还是 Prettier 的自动格式化，亦或是 Git Hooks 的强制约束，dou是为了保证团队协作的一致性。Zui近，在着手重构一个 React + TypeScript 的项目时我决定引入 ls-lint 来强制规范文件命名。配合 lint-staged，这kan起来是一个完美的组合：只在提交时检查暂存区的文件，既高效又精准。

然而现实往往比理想骨感得多。原本以为只是简单的几行配置，结果却掉进了一个关于“绝对路径”与“相对路径”的深坑。Ru果你也正在使用这套技术栈，或者正打算引入，那么这篇文章或许Neng帮你省去几个小时的抓狂调试时间。

理想中的配置：一切kan起来douhen美好

让我们来kankanZui初的配置思路。这非常直观，甚至Ke以说是教科书式的写法。

我们在项目根目录下创建了一个 .ls-lint.yml 文件，定义了严格的命名规则。比如React 组件必须使用帕斯卡命名法，而工具类文件则使用短横线命名法。配置如下：

ignore:
  - node_modules
  - .git
  - dist
ls:
  .tsx: PascalCase # React 组件文件，首字母大写
  .ts: kebab-case  # 普通逻辑文件，短横线连接
  .js: kebab-case
  .css: kebab-case

接着，在 package.json 中，我们将 ls-lint 加入到 lint-staged 的任务流中。逻辑hen简单：当匹配到 *.{ts,tsx,js,jsx} 这些文件时先运行 ESLint 修复，紧接着运行 ls-lint 检查文件名。

{
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": 
  }
}

kan起来无懈可击，对吧？按照这个规则，像 src/main.tsx 这种小写开头的文件名，在提交时理应被无情拦截并报错。毕竟我们的规则明确要求 .tsx 必须是 PascalCase。

诡异的现象：为什么坏文件也Neng“蒙混过关”？

为了测试这套配置是否生效，我特意创建了一个不符合规范的文件 src/main.tsx，然后尝试提交。

$ git add src/main.tsx
$ git commit -m "test"
✔ Preparing...
✔ Running tasks...
✔ Applying modifications...

kan到终端里绿色的对钩，我整个人dou懵了。❌ 完全不符合预期！

提交成功了？没有任何报错？ls-lint 难道是摆设吗？为了确认工具本身没问题，我决定绕过 Git Hooks，直接在终端手动运行一下命令：

$ npx ls-lint src/main.tsx
src/main.tsx failed for `.tsx` rules: pascalcase
$ echo $?
1

这就hen有意思了。手动执行时ls-lint 火眼金睛，立刻报错并退出了。可一旦把它放到 lint-staged 的流程里它就变成了“睁眼瞎”。这中间到底发生了什么？

抽丝剥茧：调试脚本揭示的真相

为了找出原因，我决定不再瞎猜，而是用数据说话。我们需要知道，lint-staged 到底把什么参数传递给了 ls-lint。

我写了一个简单的 Shell 脚本 test-ls-lint.sh，用来拦截并打印所有接收到的参数：

#!/bin/bash
# test-ls-lint.sh
echo "Arguments received: $@">> /tmp/lint-staged-debug.log
echo "Number of arguments: $#">> /tmp/lint-staged-debug.log
npx ls-lint "$@" &> /tmp/lint-staged-debug.log
exit $?

然后临时修改 package.json，让 lint-staged 调用这个脚本：

{
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": 
  }
}

尝试提交那个不合规的文件，然后去查kan日志文件 /tmp/lint-staged-debug.log

$ cat /tmp/lint-staged-debug.log
Arguments received: /Users/jesse/Web/study/React/my-app/src/main.tsx
Number of arguments: 1

真相大白！

日志显示，lint-staged 传递给 ls-lint 的，并不是我们以为的相对路径 src/main.tsx，而是完完整整的绝对路径 /Users/jesse/Web/study/React/my-app/src/main.tsx。

核心冲突：绝对路径 vs 相对路径

找到了原因，问题就解决了一半。这里存在着两个工具设计理念上的冲突：

lint-staged 的逻辑： 为了保证任务在任何工作目录下douNeng正确找到文件，它默认会将暂存文件的绝对路径作为参数传递给下游命令。这本身是为了稳健性考虑。

ls-lint 的逻辑： 它是基于项目结构工作的。它需要根据文件相对于项目根目录的路径，去匹配 .ls-lint.yml 中定义的规则。当它接收到一个绝对路径时它似乎“迷路”了无法正确解析文件在项目中的相对位置，从而导致规则匹配失效，甚至静默放行。

为了验证这一点，我直接在终端用绝对路径测试了一下 ls-lint

# 测试 1：相对路径
$ npx ls-lint src/main.tsx
src/main.tsx failed for `.tsx` rules: pascalcase
$ echo $?
1
# 测试 2：绝对路径
$ npx ls-lint /Users/jesse/Web/study/React/my-app/src/main.tsx
$ echo $?
0

果然这就是罪魁祸首。当传入绝对路径时ls-lint 的检测机制被绕过了。这个问题在 GitHub 的 Issue 列表中也有其他开发者反馈，kan来我并不是唯一的受害者。

终极解决方案：绕过 lint-staged，回归 Husky

既然 lint-staged 坚持传绝对路径，而 ls-lint 又只认相对路径，那我们只Neng换个思路了。

Zui优雅的解决方案是：不再通过 lint-staged 来调用 ls-lint，而是直接在 Husky 的 pre-commit 钩子中处理。

我们Ke以利用 Git 自身的命令 git diff --staged --name-only 来获取暂存区文件的列表。这个命令输出的正是我们梦寐以求的相对路径！

第一步：修改 package.json

把 ls-lint 从 lint-staged 的配置中移除，只保留代码检查相关的工具：

{
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": ,
    "*.{css,scss}": "stylelint --fix"
  }
}

第二步：重写 .husky/pre-commit

接下来编辑 .husky/pre-commit 文件。我们需要在执行 lint-staged 之前，先手动跑一遍 ls-lint。

#!/usr/bin/env sh
. "$/_/husky.sh"
# 1. 检查暂存文件的命名规范
pnpm exec ls-lint $
# 2. 执行其他 lint-staged 检查
pnpm exec lint-staged

这里有几个关键点需要注意：

相对路径获取： git diff --staged --name-only 会列出所有暂存文件的相对路径。Ru果是第一次提交，这个命令依然Neng正常工作。

空暂存区处理： Ru果暂存区为空，这个命令会返回空字符串，ls-lint 接收到空参数通常会直接跳过检查，不会报错，所以是安全的。

Yi删除文件： git diff 的列表里可Neng会包含刚刚被 git rm 删除的文件。不过不用担心，ls-lint 在检查时会发现文件不存在从而自动忽略它们，不会影响整体流程。

验证成果：完美拦截

配置修改完毕，现在是见证奇迹的时刻。我们 尝试提交那个不合规的 src/main.tsx

$ git add src/main.tsx
$ git commit -m "test"
src/main.tsx failed for `.tsx` rules: pascalcase
husky - pre-commit hook exited with code 1 

✅ 成功拦截！

现在ls-lint 终于发挥了它应有的作用，检测到了命名问题并阻止了提交。再试一次提交符合规范的文件，比如 src/MainComponent.tsx

$ git add src/MainComponent.tsx
$ git commit -m "feat: add main component"
✔ Preparing...
✔ Running tasks...
✔ Applying modifications...

✅ 正常通过！

这次踩坑经历让我深刻意识到，工具链之间的集成并不总是 1+1=2 那么简单。lint-staged 为了通用性选择了绝对路径，而 ls-lint 为了配置的简洁性依赖相对路径，这种设计上的错位在特定场景下就会引发难以察觉的 Bug。

虽然我们通过在 Husky 钩子中直接调用 Git 命令解决了问题，但这毕竟是一个“Workaround”。好消息是ls-lint 的开发团队Yi经注意到了这个问题。根据 GitHub 上的反馈，他们计划在未来的 v2.0 版本中增加对绝对路径的原生支持。

但在那个版本发布并普及之前，使用 git diff --staged --name-only 配合 Husky 无疑是Zui稳定、Zui可靠的方案。希望这篇文章Neng帮你避开这个隐蔽的坑，让你的代码规范之路geng加平坦！

---