Rust代码格式化工具stylua的使用：高效、可配置的Lua代码格式化库

简介

StyLua是一个用Rust编写的Lua代码格式化工具，支持多种Lua方言，包括Lua 5.1、5.2、5.3、5.4、LuaJIT、Luau和CfxLua/FiveM Lua。它基于full-moon解析器构建，采用确定性格式化算法，主要遵循Roblox Lua风格指南，同时提供自定义配置选项。

安装方法

从GitHub Releases安装

可以直接下载预编译的二进制文件，默认支持所有Lua语法变体。

使用Cargo安装

对于已安装Rust环境的用户，可以通过Cargo安装：

# 安装基础版本
cargo install stylua

# 按需选择特定Lua版本支持
cargo install stylua --features lua52  # 支持Lua 5.2
cargo install stylua --features lua53  # 支持Lua 5.3
cargo install stylua --features luau   # 支持Luau方言

其他安装方式

支持多种安装渠道：

• 通过npm安装
• 使用Homebrew安装
• 作为GitHub Action使用
• 通过Docker容器运行
• 作为VSCode扩展安装

基础使用

安装后，可以通过命令行格式化Lua文件：

# 格式化单个文件
stylua example.lua

# 格式化整个目录
stylua src/

# 检查文件是否需要格式化(不实际修改)
stylua --check example.lua

配置示例

示例代码展示

-- 忽略整个矩阵的格式化
-- stylua: ignore
local matrix = {
    { 0, 0, 0 },
    { 0, 0, 0 },
    { 0, 0, 0 },
}

-- 格式化此变量
local foo = true

-- 忽略代码块格式化
-- stylua: ignore start
local   bar   =   false
local  baz      = 0
-- stylua: ignore end

-- 格式化此变量
local foobar = false

配置文件示例(stylua.toml)

# 支持所有Lua语法变体
syntax = "All"

# 行宽限制
column_width = 100

# 使用Unix风格换行符
line_endings = "Unix"

# 缩进配置
indent_type = "Spaces"  # 使用空格而非Tab
indent_width = 2        # 2空格缩进

# 字符串引号偏好
quote_style = "AutoPreferSingle"  # 自动选择，优先单引号

# 函数调用括号
call_parentheses = "Always"  # 总是保留括号

# 不折叠简单语句
collapse_simple_statement = "Never"

# 禁用require语句排序
[sort_requires]
enabled = false

完整功能示例

1. 格式化整个项目

# 递归格式化项目目录下所有.lua文件
stylua .

2. 与版本控制系统集成

# 只格式化暂存区中的Lua文件
git diff --name-only --cached | grep '.lua$' | xargs stylua

3. 使用不同配置

# 使用指定配置文件格式化
stylua --config-path .stylua.toml src/

4. 作为预提交钩子

# 在.git/hooks/pre-commit中添加
stylua --check $(git diff --name-only --cached | grep '.lua$')
if [ $? -ne 0 ]; then
  echo "Code needs formatting, run 'stylua' first"
  exit 1
fi

高级特性

1. 部分格式化：可以精确控制哪些代码段需要跳过格式化
2. 语法验证：使用--verify选项确保格式化后代码语法正确
3. 差异检查：--check模式适合CI环境集成
4. 多方言支持：通过配置支持不同Lua方言的特定语法

编辑器集成配置

Neovim配置示例

-- 使用null-ls集成StyLua
local null_ls = require("null-ls")
null_ls.setup({
    sources = {
        null_ls.builtins.formatting.stylua.with({
            extra_args = { "--config-path", vim.fn.expand("~/.config/nvim/stylua.toml") },
        }),
    },
})

VSCode配置

{
    "editor.defaultFormatter": "JohnnyMorganz.stylua",
    "stylua.configPath": ".stylua.toml",
    "[lua]": {
        "editor.formatOnSave": true
    }
}

常见问题解决

1. 忽略特定代码块：

   -- stylua: ignore start
   local badly_formatted = {
       a = 1,   b=2,
       c=3
   }
   -- stylua: ignore end
   

2. 处理长字符串：

   local long_string = [[
   This is a long string that won't be reformatted
   because it's in a multiline literal.
   ]]
   

3. 自定义缩进：

   # 在stylua.toml中
   indent_type = "Spaces"
   indent_width = 2  # 2空格缩进
   

StyLua通过其丰富的配置选项和稳定的格式化能力，成为Lua开发者提升代码一致性和可读性的强大工具。