Conform.nvim 中 Stylua 格式化配置失效问题解析

问题现象

在使用 Conform.nvim 插件配合 Stylua 格式化工具时，用户发现 Stylua 无法正确应用项目根目录下的 stylua.toml 配置文件。具体表现为：

1. 通过 :lua require("conform").format() 命令执行格式化时，文件内容无变化
2. 直接在终端运行 stylua <文件名> 却能正常格式化
3. 调试日志显示 Stylua 命令执行成功（退出码为0）

技术分析

配置加载机制

Stylua 作为 Lua 代码格式化工具，支持通过 --search-parent-directories 参数从当前工作目录向上递归查找配置文件。Conform.nvim 默认会传递以下参数：

{
    "--search-parent-directories",
    "--stdin-filepath",
    "/path/to/file.lua",
    "-"
}

这种设计理论上应该能够正确加载项目根目录下的配置文件。

常见排查方向

1. 工作目录问题：Conform.nvim 执行时的当前工作目录可能与预期不符
2. 配置文件位置：stylua.toml 可能不在预期的父目录层级中
3. 忽略规则干扰：.styluaignore 文件可能导致特定目录被忽略
4. 版本兼容性：不同版本的 Stylua 可能有不同的配置文件加载逻辑

解决方案

验证步骤

1. 确认 Stylua 版本：stylua --version
2. 检查当前工作目录：:pwd 或通过调试日志查看
3. 确认配置文件路径：确保 stylua.toml 位于预期的父目录中
4. 检查忽略文件：查看是否存在 .styluaignore 及其内容

高级配置

如需特殊处理，可以修改 Conform.nvim 的 Stylua 参数：

require("conform.formatters.stylua").args = {
    "--search-parent-directories",
    "$FILENAME"
}
require("conform.formatters.stylua").stdin = false

注意设置 stdin = false 可避免需要手动执行 :e 重新加载文件。

最佳实践

1. 将 stylua.toml 放置在项目根目录
2. 谨慎使用 .styluaignore，确保不会意外忽略需要格式化的目录
3. 保持 Stylua 版本更新（推荐使用最新稳定版）
4. 对于复杂项目结构，明确指定配置文件路径可能更可靠

总结

该问题通常源于配置文件的查找路径被意外限制，而非 Conform.nvim 或 Stylua 本身的功能缺陷。通过系统性地检查配置文件位置、忽略规则和工作目录，大多数情况下都能快速定位并解决问题。理解工具链的配置加载机制有助于更高效地排查类似问题。