一个针对 Lua 5.1、5.2、5.3、5.4 和 Luau 的有态度代码格式化工具，使用 full-moon 构建。StyLua 受到 prettier 等工具的启发，它会解析你的 Lua 代码库，并从头开始打印出来，强制执行一致的代码风格。

StyLua 主要遵循 Roblox Lua 风格指南，有一些偏差。

安装

有几种方式可以安装 StyLua

通过 GitHub 发布

预构建的二进制文件可在 GitHub 发布页面 上找到。

默认情况下，这些二进制文件是使用 所有语法变体启用（Lua 5.2、5.3、5.4 和 Luau） 来覆盖所有可能的代码库。如果你只想格式化特定版本的 Lua，请参阅 从 crates.io 安装。

从 Crates.io

如果你已经安装了 Rust，你可以使用 cargo 安装 StyLua。默认情况下，它为 Lua 5.1 构建。你可以传递 --features <flag> 参数来为 Lua 5.2 (lua52)、Lua 5.3 (lua53)、Lua 5.4 (lua54) 或 Luau (luau) 构建

cargo install stylua
cargo install stylua --features lua52
cargo install stylua --features lua53
cargo install stylua --features lua54
cargo install stylua --features luau

GitHub Actions

你可以在你的 CI 中使用 stylua-action GitHub Action 来安装和运行 StyLua。此操作使用预构建的 GitHub 发布二进制文件，而不是运行 cargo install，以加快 CI 时间。

pre-commit

您可以使用StyLua与pre-commit一起使用。有3种可能的pre-commit钩子可用

• stylua：通过cargo安装 - 需要Rust工具链
• stylua-system：运行PATH上可用的stylua二进制文件。该二进制文件必须预先安装
• stylua-github：自动从GitHub Actions安装相关的预构建二进制文件

将以下内容添加到您的.pre-commit-config.yaml文件中

- repo: https://github.com/JohnnyMorganz/StyLua
  rev: v0.20.0
  hooks:
    - id: stylua # or stylua-system / stylua-github

npm

StyLua可以作为二进制文件在npm上发布，地址为@johnnymorganz/stylua-bin。这是一个轻量级的包装器，用于安装二进制文件并通过npm运行

npx @johnnymorganz/stylua-bin --help

StyLua还可以在@johnnymorganz/stylua处作为WASM库使用。它可以在Node.js或浏览器（使用打包器）中使用

Docker

StyLua可在Docker Hub上找到。

如果您正在使用Docker，安装StyLua最简单的方法是

COPY --from=JohnnyMorganz/StyLua:0.20.0 /stylua /usr/bin/stylua

Homebrew

您可以通过Homebrew包管理器在macOS上安装StyLua。

brew install stylua

其他安装方法

• VSCode扩展
• Aftman

aftman add johnnymorganz/[email protected]

• A社区维护的包仓库。请注意，这些包由第三方维护，我们不控制它们的打包清单。

其他编辑器集成

请注意，这些集成需要在您的系统上已安装并可用StyLua二进制文件。

• Sublime: Sublime Text包
• Neovim: stylua-nvim / stylua.nvim

使用方法

安装后，将需要格式化的文件传递给CLI

stylua src/ foo.lua bar.lua

此命令将格式化foo.lua和bar.lua文件，并在src目录中搜索以格式化其中的任何文件。StyLua还可以通过使用-作为文件名从stdin读取。

glob过滤

默认情况下，当遍历目录时，StyLua会查找匹配glob **/*.lua（或当启用luau时为**/*.luau）的所有文件以进行格式化。您也可以指定在搜索时匹配的显式glob模式

stylua --glob '**/*.luau' -- src # format all files in src matching **/*.luau
stylua -g '*.lua' -g '!*.spec.lua' -- . # format all Lua files except test files ending with `.spec.lua`

注意，如果您正在使用glob参数，它可以接受多个字符串，因此需要在glob模式与要格式化的文件之间使用--来分隔。

默认情况下，glob过滤（以及.styluaignore文件）仅在目录遍历和搜索时应用。直接传递的文件（例如stylua foo.txt）将覆盖glob / 忽略，并始终进行格式化。要禁用此行为，请传递--respect-ignores标志（stylua --respect-ignores foo.txt）。

使用.styluaignore进行过滤

您可以创建一个与.gitignore格式相似的.styluaignore文件。任何与忽略文件中的glob匹配的文件都将被StyLua忽略。例如，对于以下内容的.styluaignore文件

vendor/

运行stylua .将忽略vendor/目录。

--check：检查文件的格式化

要检查文件是否已格式化（但不直接写入它们），请使用--check标志。它将接受文件作为输入，并将diff输出到stdout而不是重写文件内容。如果存在尚未完全格式化的文件，StyLua将退出并返回状态码1。

默认情况下，我们提供了一个自定义的标准diff视图，但这可以配置

• --output-format=unified：输出统一diff，可以被patch或delta等工具消费
• --output-format=json：输出表示更改的JSON，对机器可读输出很有用

--verify：验证格式化输出

作为安全措施，可以将--verify标志传递给StyLua，StyLua将在保存到文件之前验证所有格式化输出。

如果启用，该工具将重新解析格式化输出以验证AST是否仍然有效（没有语法错误）并且与输入相似（可能存在语义更改）。

在大型代码库中采用StyLua时很有用，在那里很难验证所有格式化是否正确。请注意，这可能会产生错误阳性或阴性 - 我们建议进行手动验证以及运行测试以确认。

忽略文件的一部分

要跳过格式化文件的一部分，您可以在它之前添加-- stylua: ignore。如果需要保留特定风格以提高可读性，这可能很有用，例如。

-- stylua: ignore
local matrix = {
    { 0, 0, 0 },
    { 0, 0, 0 },
    { 0, 0, 0 },
}

也可以使用-- stylua: ignore start和-- stylua: ignore end来跳过代码块。

local foo = true
-- stylua: ignore start
local   bar   =   false
local  baz      = 0
-- stylua: ignore end
local foobar = false

请注意，忽略不能跨越作用域边界 - 退出一个块后，格式化将重新启用。

格式化范围

要格式化文件中的特定范围，请使用--range-start <num>和/或--range-end <num>。这两个参数都是包含和可选的 - 如果未提供参数，则分别使用文件的开始/结束。

只有位于范围内的整个语句将被格式化。如果语句的一部分位于范围之外，则该语句将被忽略。

在编辑器中，支持格式化选择。

需要排序

StyLua内置了对排序require语句的支持。我们将连续的require语句分组到一个“块”中，然后只在该块内对require进行排序。require块不会在文件中移动。

我们只包含以下形式的 requires：local NAME = require(EXPR)，并根据 NAME 进行字典序排序。（我们还会对以下形式的 Roblox 服务进行排序：local NAME = game:GetService(EXPR)）

默认情况下，排序是关闭的。要启用它，请在您的 stylua.toml 中添加以下内容

[sort_requires]
enabled = true

配置

StyLua 是 有观点的，所以只提供了一些选项。

查找配置

CLI 在工具执行目录中查找 stylua.toml 或 .stylua.toml。如果未找到，我们将搜索 .editorconfig 文件，否则回退到默认配置。此功能可以使用 --no-editorconfig 禁用。有关更多详细信息，请参阅 EditorConfig。

可以使用 --config-path <path> 提供自定义路径。如果提供的路径未找到/格式不正确，StyLua 将出错退出。

默认情况下，工具不会搜索当前目录之外的目录。可以使用 --search-parent-directories 启用递归搜索父目录。这将保持对祖先的搜索。如果未找到，它将在 $XDG_CONFIG_HOME / $XDG_CONFIG_HOME/stylua 中查找。

注意：由于可能存在冲突格式的问题，因此不建议在当前目录之外搜索

建议在项目根目录中保留一个 .stylua.toml 文件，以便其他开发者可以使用相同的配置。

如果项目在没有配置文件的情况下使用 StyLua 的默认配置，启用外部搜索可能会引起冲突格式。

选项

StyLua 只提供以下选项

默认 stylua.toml，注意如果您想使用默认值，则无需显式指定每个选项

column_width = 120
line_endings = "Unix"
indent_type = "Tabs"
indent_width = 4
quote_style = "AutoPreferDouble"
call_parentheses = "Always"
collapse_simple_statement = "Never"

[sort_requires]
enabled = false