名称: shfmt配置用户可调用: false 描述: 用于配置shfmt进行shell脚本格式化，包括.shfmt.toml设置、EditorConfig集成和项目特定设置。允许工具:

读取
写入
编辑
Bash
Grep
Glob

shfmt配置

掌握shfmt配置，实现跨项目的shell脚本格式化一致性，包括配置文件、EditorConfig集成和团队标准化。

概述

shfmt是一个shell解析器、格式化器和解释器，支持POSIX Shell、Bash和mksh。配置允许您为shell脚本定义一致的格式化规则。

配置方法

shfmt支持多种配置方法，按优先级排序：

命令行标志（最高优先级）
EditorConfig设置
.shfmt.toml或shfmt.toml文件

TOML配置文件

基本配置

在项目根目录创建.shfmt.toml或shfmt.toml：

# Shell方言（posix、bash、mksh、bats）
shell = "bash"

# 缩进使用空格（0为制表符）
indent = 2

# 二进制运算符在行首
binary-next-line = true

# 切换用例缩进
switch-case-indent = true

# 重定向运算符后跟空格
space-redirects = false

# 保持列对齐填充
keep-padding = false

# 函数开括号在下一行
func-next-line = false

配置选项解释

shell

指定shell方言以进行解析：

# POSIX兼容shell（最便携）
shell = "posix"

# Bash（.bash文件的默认值）
shell = "bash"

# MirBSD Korn Shell
shell = "mksh"

# Bats（Bash自动化测试系统）
shell = "bats"

如果未指定，基于shebang自动检测：

#!/bin/sh -> posix
#!/bin/bash 或 #!/usr/bin/env bash -> bash
#!/bin/mksh -> mksh

indent

控制缩进样式：

# 2个空格（常见）
indent = 2

# 4个空格
indent = 4

# 制表符（使用0）
indent = 0

binary-next-line

控制二进制运算符位置：

# 运算符在行末（默认）
binary-next-line = false

# 结果：
if [ "$a" = "foo" ] &&
   [ "$b" = "bar" ]; then
    echo "match"
fi

# 运算符在下一行首
binary-next-line = true

# 结果：
if [ "$a" = "foo" ] \
    && [ "$b" = "bar" ]; then
    echo "match"
fi

switch-case-indent

控制case语句缩进：

# 案例与switch同级（默认）
switch-case-indent = false

# 结果：
case "$1" in
start)
    do_start
    ;;
stop)
    do_stop
    ;;
esac

# 案例在switch内缩进
switch-case-indent = true

# 结果：
case "$1" in
    start)
        do_start
        ;;
    stop)
        do_stop
        ;;
esac

space-redirects

控制重定向周围空格：

# 重定向前无空格（默认）
space-redirects = false

# 结果：
echo "hello" >file.txt
cat <input.txt

# 重定向前有空格
space-redirects = true

# 结果：
echo "hello" > file.txt
cat < input.txt

keep-padding

保留对齐填充：

# 移除额外对齐空格（默认）
keep-padding = false

# 输入带对齐：
short="value"
longer_var="another"

# 结果（对齐移除）：
short="value"
longer_var="another"

# 保持对齐
keep-padding = true

# 结果（对齐保持）：
short=     "value"
longer_var="another"

func-next-line

控制函数括号位置：

# 开括号在同一行（默认）
func-next-line = false

# 结果：
my_function() {
    echo "hello"
}

# 开括号在下一行
func-next-line = true

# 结果：
my_function()
{
    echo "hello"
}

EditorConfig集成

shfmt尊重EditorConfig设置。创建或更新.editorconfig：

# EditorConfig很棒：https://EditorConfig.org

root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.sh]
indent_style = space
indent_size = 2

# shfmt特定选项
shell_variant = bash
binary_next_line = true
switch_case_indent = true
space_redirects = false
keep_padding = false
function_next_line = false

EditorConfig选项映射

shfmt标志	EditorConfig键
`-i`	`indent_size`（0为制表符）
`-ln`	`shell_variant`
`-bn`	`binary_next_line`
`-ci`	`switch_case_indent`
`-sr`	`space_redirects`
`-kp`	`keep_padding`
`-fn`	`function_next_line`

命令行标志

基本用法

# 原地格式化文件
shfmt -w script.sh

# 显示更改差异
shfmt -d script.sh

# 列出需要格式化的文件
shfmt -l .

# 格式化并输出到stdout
shfmt script.sh

格式化选项

# 设置缩进为4个空格
shfmt -i 4 script.sh

# 使用制表符缩进
shfmt -i 0 script.sh

# 指定shell方言
shfmt -ln bash script.sh

# 二进制运算符在下一行
shfmt -bn script.sh

# 缩进切换用例
shfmt -ci script.sh

# 重定向后加空格
shfmt -sr script.sh

# 保留填充
shfmt -kp script.sh

# 函数括号在下一行
shfmt -fn script.sh

组合示例

# 常见配置
shfmt -i 2 -ci -bn -w script.sh

项目配置模式

最小Bash项目

# .shfmt.toml
shell = "bash"
indent = 2

POSIX兼容脚本

# .shfmt.toml
shell = "posix"
indent = 4
binary-next-line = false
switch-case-indent = false

现代Bash所有功能

# .shfmt.toml
shell = "bash"
indent = 2
binary-next-line = true
switch-case-indent = true
space-redirects = false
func-next-line = false

团队标准化

# .shfmt.toml - 强制执行团队标准
shell = "bash"
indent = 2
binary-next-line = true
switch-case-indent = true
keep-padding = false

CI/CD集成

GitHub Actions

名称: Shell格式检查
用户可调用: false
触发: [推送, 拉取请求]
作业:
  shfmt:
    运行于: ubuntu-latest
    步骤:
      - 使用: actions/checkout@v4
      - 名称: 安装shfmt
        运行: |
          curl -sS https://webinstall.dev/shfmt | bash
          export PATH="$HOME/.local/bin:$PATH"
      - 名称: 检查格式化
        运行: shfmt -d .

Pre-commit钩子

# .pre-commit-config.yaml
存储库:
  - 仓库: https://github.com/scop/pre-commit-shfmt
    修订: v3.8.0-1
    钩子:
      - id: shfmt
        参数: ["-w"]

Makefile目标

.PHONY: fmt-check fmt

fmt-check:
 shfmt -d .

fmt:
 shfmt -w .

最佳实践

提交配置 - 始终提交.shfmt.toml以确保团队一致性
匹配方言 - 设置shell以匹配脚本shebang
优先EditorConfig - 使用EditorConfig进行IDE集成
CI强制执行 - 在CI中运行shfmt -d以捕获格式化问题
一致缩进 - 选择2或4个空格并保持一致
文档化选择 - 添加注释解释非默认选项
版本锁定 - 在CI中固定shfmt版本以实现可重复性

故障排除

配置未应用

检查优先级顺序：

命令行标志覆盖一切
文件目录中的EditorConfig
项目根目录中的.shfmt.toml

错误Shell方言

验证shebang匹配配置：

# 如果使用shell = "bash"，确保脚本有：
#!/usr/bin/env bash
# 或
#!/bin/bash

EditorConfig未检测到

确保EditorConfig文件在父目录链中并有正确部分：

[*.sh]
shell_variant = bash

何时使用此技能

在新项目中设置shfmt
配置团队范围的格式化标准
将shfmt与CI/CD管道集成
故障排除配置问题
迁移配置方法之间
为shell脚本设置EditorConfig