技能使用指南

shfmt-configuration（shfmt配置）Skill 是什么？如何下载？

shfmt配置技能帮你快速生成 .shfmt.toml 与 EditorConfig 配置，统一团队 Shell 脚本的方言、缩进与换行风格。讲清命令行、EditorConfig 与 TOML 的优先级关系，附 GitHub Actions、pre-commit 集成模板与故障排查路径。现在了解如何安装使用，让代码评审不再被格式问题淹没。

shfmt配置技能Skillshfmt-configuration
8 个章节 约 16 分钟阅读 AI 智能生成

shfmt配置：一份配置文件，统一全团队的 Shell 脚本格式

  • 它是什么：一个专注于 shfmt 配置层面的 AI 技能，帮你写出规范可用的 .shfmt.toml、.editorconfig，并说明命令行标志、EditorConfig、TOML 文件三者之间的优先级关系。
  • 它解决什么：Shell 脚本缩进忽大忽小、&& 换行位置各写各的、case 分支缩进靠个人习惯、CI 里没有格式校验、新人接手老脚本不敢动——这些“格式内耗”都能被一份配置收敛掉。
  • 能带来什么：覆盖 4 种 Shell 方言（posix / bash / mksh / bats）、7 个核心格式化选项、4 套项目模板、3 类 CI/CD 集成示例，以及一套配置未生效时的排查思路。
  • 怎么用：把项目背景和团队偏好告诉 AI 助手，让它按模板生成配置、解释每个选项的取舍，再配合 shfmt -d . 在本地和 CI 上验证。
  • 适合谁：需要给新项目定规矩的运维/后端工程师、负责代码规范落地的技术负责人、维护大量历史 Shell 脚本的平台团队。

1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？

基本信息

项目 内容
技能中文名 shfmt配置
技能英文名 shfmt-configuration
技能ID 13850
技能定位 Shell 脚本格式化配置指导（配置文件、EditorConfig 集成、团队标准化）
元数据标注 用户可调用：false（以官方说明为准）

它解决什么问题

shfmt 本身是一个成熟的 shell 解析器、格式化器和解释器，支持 POSIX Shell、Bash 和 mksh。真正让人头疼的往往不是“不会运行 shfmt”，而是：

  1. 不知道该写 .shfmt.toml 还是 shfmt.toml，放哪个目录才对；
  2. 不清楚命令行标志、EditorConfig、TOML 文件三者冲突时谁说了算；
  3. binary-next-line、switch-case-indent、keep-padding 这类选项光看名字猜不出效果；
  4. 想接进 GitHub Actions 或 pre-commit，却卡在版本固定和路径问题上。

这个技能就是把这些“配置层的知识”整理成可直接套用的方案。需要注意的是，技能元数据中标注为“用户可调用：false”，意味着它更偏向知识型/配置指导型技能，通常由 AI 助手在对话中参考其内容来回答与生成配置，而不是作为一个可直接执行的功能入口（具体接入方式以官方说明为准）。

一键安装的思路与步骤

由于该技能的具体上架入口、命令与订阅方式未在技能详情中提供，以下为通用流程，实际操作时以官方说明为准：

  1. 确认前提：项目里确实存在 .sh、.bash 脚本或 Bats 测试文件；本机最好已经装好 shfmt，方便立刻验证配置效果。技能详情中给出的安装方式为 curl -sS https://webinstall.dev/shfmt | bash。
  2. 找到技能：在技能市场/技能库中搜索英文名 shfmt-configuration，或用技能ID 13850 精确定位。
  3. 添加技能：按平台提供的“添加/启用”按钮完成挂载，使其进入 AI 助手可参考的技能集合。
  4. 验证是否生效：在对话中直接提问，例如“帮我在项目根目录生成一份 .shfmt.toml，使用 bash 方言、2 空格缩进、二进制运算符换到下一行”。如果返回的内容包含 shell = "bash"、indent = 2、binary-next-line = true 等条目，并解释了优先级关系，说明技能已被正确引用。
  5. 落地验证：在终端执行 shfmt -d . 查看差异，shfmt -w . 落地格式化，确认配置真的在起作用。

2. 该技能的主要功能和特点

  • TOML 配置文件生成：支持在项目根目录创建 .shfmt.toml 或 shfmt.toml，覆盖 shell、indent、binary-next-line、switch-case-indent、space-redirects、keep-padding、func-next-line 七个核心选项。
  • 方言识别与自动推断：明确 posix、bash、mksh、bats 四种方言的差异，并说明未指定时如何依据 shebang 自动检测（#!/bin/sh → posix，#!/bin/bash 或 #!/usr/bin/env bash → bash，#!/bin/mksh → mksh）。
  • 配置优先级判定：清晰给出三层优先级——命令行标志最高，其次是目录中的 EditorConfig，最后是项目根目录的 .shfmt.toml。这条规则能直接解决“我明明写了配置为什么没生效”的高频困惑。
  • EditorConfig 集成与选项映射：提供 .editorconfig 示例，并给出 shfmt 标志与 EditorConfig 键的一一对应表（-i → indent_size、-ln → shell_variant、-bn → binary_next_line、-ci → switch_case_indent、-sr → space_redirects、-kp → keep_padding、-fn → function_next_line）。这一点比“只给 TOML”的方案更实用，因为 IDE 与编辑器普遍认 EditorConfig。
  • 带前后对比的效果说明：每个选项都配有“默认值输出”和“开启后输出”的代码示例，无需试错就能判断是否符合团队审美。
  • 项目配置模板：内置“最小 Bash 项目”“POSIX 兼容脚本”“现代 Bash 全功能”“团队标准化”四套现成模板，覆盖从个人小工具到多人协作仓库的场景。
  • CI/CD 集成示例：给出 GitHub Actions（安装 shfmt 后运行 shfmt -d . 做格式卡口）、pre-commit 钩子（scop/pre-commit-shfmt）与 Makefile 目标（fmt-check / fmt）三种落地方式。
  • 故障排查路径：针对“配置未应用”“Shell 方言错误”“EditorConfig 未被检测到”给出可执行的检查顺序。

和普通工具比强在哪：shfmt 只负责“执行格式化”，本技能负责“决定该怎么格式化”。它把散落在文档、issue 和口口相传里的配置经验，压缩成一份可提交、可评审、可复用的配置决策。

3. 如何使用该技能？

以下为典型的分步使用流程，可直接照着提问。

步骤 1：明确项目方言与缩进基线

先告诉助手项目情况，例如：“这是一个纯 Bash 的部署脚本仓库，团队约定 2 空格缩进，case 分支要缩进，&& 和 || 换行到下一行行首。”

步骤 2：生成 .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

步骤 3：生成配套的 .editorconfig

让助手输出 EditorConfig 版本，供 IDE 复用同一套规则，例如 [*.sh] 段落中设置 indent_style = space、indent_size = 2，并追加 shell_variant = bash、binary_next_line = true 等 shfmt 专属键。

步骤 4：本地验证

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

# 查看差异，不改文件
shfmt -d script.sh

# 原地格式化
shfmt -w .

输入示例：一个 case 语句未缩进的脚本；输出说明：shfmt -d 会打印 unified diff，确认差异只涉及缩进与换行、无逻辑改动后再执行 -w。

步骤 5：临时覆盖与组合

需要临时改变风格时，用命令行标志覆盖配置，例如 shfmt -i 4 -ci -bn -w script.sh。此时以命令行参数为准，这也是排查“为什么我的 TOML 没生效”的第一检查点。

步骤 6：接入 CI

让助手生成 GitHub Actions 工作流：检出代码 → 安装 shfmt（curl -sS https://webinstall.dev/shfmt | bash 并把 $HOME/.local/bin 加入 PATH）→ 执行 shfmt -d .。也可以改造成 pre-commit 钩子或 Makefile 的 fmt-check 目标。

步骤 7：提交并文档化

把配置文件和 CI 改动一起提交，并在配置里用注释解释非默认选项的原因，避免后人“优化”掉。

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
shfmt配置技能（本技能） 配置知识与方案生成 TOML/EditorConfig 生成、优先级解释、CI 模板、故障排查 低：对话式提问即可，无需背诵选项含义 新项目定规、团队标准化、CI 接入、配置排错 优势：把配置决策讲清楚，模板可直接落地；不足：不替代 shfmt 本体执行，具体入口与调用方式以官方说明为准
直接查阅 shfmt 官方文档手动配置 原始权威资料 全部选项与标志的完整定义 中：需要自行归纳优先级与组合方式 需要极致细节或排查边角问题 优势：最权威、最全；不足：知识密度分散，缺少“团队该选什么”的建议
shellcheck Shell 脚本静态缺陷检查 语法陷阱、引用错误、常见漏洞告警 中：需单独安装并调整忽略规则 代码正确性与安全检查 优势：能发现真实缺陷；不足：不做格式化，与 shfmt 属于互补而非替代
Prettier 生态中的格式化方案 多语言统一格式化 通过插件覆盖多种语言 中高：需引入插件并处理与 shfmt 规则的冲突 前端为主、脚本量少的仓库 优势：一套工具管多语言；不足：Shell 支持依赖插件，风格选项不如 shfmt 细致，易与团队 Shell 规范打架

选择建议：如果仓库以 Shell 脚本为主、需要精细控制缩进与换行风格，优先 shfmt 系方案；如果仓库是多语言前端项目、Shell 只是零星辅助脚本，可考虑统一到既有格式化器上，减少工具链数量。

5. 该技能的典型应用场景与实际体验情况

场景一：运维工程师给新仓库定规矩

角色：负责 CI 与发布流水线的运维工程师。痛点：仓库里十几个部署脚本来自不同人，缩进 2 空格、4 空格、Tab 混杂，case 分支缩进风格各异。使用方式：把方言与团队偏好告诉助手，一次性生成 .shfmt.toml 和 .editorconfig，再跑一次 shfmt -w . 全量落地。实际体验：第一次全量格式化会产生大 diff，建议单独提交一个“仅格式化”的 commit，便于评审时跳过；后续增量提交就很干净。

场景二：技术负责人推动团队标准化

角色：负责代码规范落地的 Tech Lead。痛点：Code Review 里大量评论是“这里缩进不对”，浪费时间。使用方式：用技能里的“团队标准化”模板确定配置，配上 EditorConfig 保证 IDE 自动对齐，再加 pre-commit 钩子拦截。实际体验：上手的难点不在配置本身，而在“说服大家接受一次大 diff”；建议先文档化选项理由，再统一提交。注意钩子要固定版本，保证可重复。

场景三：CI 卡口与格式化回归

角色：平台工程师。痛点：本地规范靠自觉，CI 里没有强制校验，久而久之规范形同虚设。使用方式：让助手生成 GitHub Actions 工作流，安装 shfmt 后执行 shfmt -d .，有差异就让流水线失败。实际体验：-d 只输出 diff 不改文件，是最安全的卡口方式；注意 CI 中要固定 shfmt 版本，否则升级后可能出现新的格式化差异导致大面积失败。

场景四：配置不生效的排错

角色：刚接手项目的开发者。痛点：明明写了 .shfmt.toml，结果格式化行为和预期不一致。使用方式：按技能的排查路径逐一核对——是否被命令行标志覆盖、.editorconfig 是否在父目录链中、shell 是否与脚本 shebang 匹配。实际体验：绝大多数“配置失灵”都是优先级问题或 shebang 与 shell 不一致，这条排查顺序能显著缩短定位时间。

6. 该技能能为用户带来的价值

  • 把“隐性规范”变成“可提交的配置”：过去团队风格靠口头约定和 Review 评论传递，现在落成 .shfmt.toml + .editorconfig 两三个文件，新人 clone 下来即符合规范。
  • 显著降低配置门槛：不用逐个试 -bn、-ci、-kp 的效果，也不用读完整个选项表；带前后对比的示例让“选中即所见”。
  • 缩短排错时间：三层优先级的明确说明，能把“配置没生效”这一类问题从“反复试错”变成“按顺序检查”。
  • 减少评审噪音：格式类评论被工具和 CI 吸收，Review 聚焦在逻辑、边界条件和安全性上。
  • 长期可维护：四套项目模板 + 七条最佳实践（提交配置、匹配方言、优先 EditorConfig、CI 强制执行、统一缩进、文档化选择、版本锁定）构成了一套可传承的工程习惯，而不是一次性的格式化操作。

7. 常见问题 FAQ

Q1：这个技能怎么安装？安装后能直接运行 shfmt 吗？ A：技能本身按平台的“添加/启用”流程挂载，搜索英文名 shfmt-configuration 或技能ID 13850 即可，具体入口与命令以官方说明为准。它负责配置知识与方案生成，实际格式化仍由本地或 CI 中的 shfmt 可执行文件完成，详情中给出的安装方式是 curl -sS https://webinstall.dev/shfmt | bash。

Q2：使用这个技能收费吗？ A：技能详情中未包含任何价格信息，是否收费、有无额度限制请以官方说明为准。

Q3：我写了 .shfmt.toml，为什么格式化结果没变化？ A：按优先级排查：命令行标志优先级最高，会覆盖配置文件；其次是文件所在目录的 EditorConfig；最后才是项目根目录的 .shfmt.toml。此外还要确认 shell 设置与脚本 shebang 一致，以及 EditorConfig 确实位于父目录链且包含 [*.sh] 段落。

Q4：.shfmt.toml 和 .editorconfig 应该选哪个？ A：两者都能用，且可以共存。如果团队用多种编辑器、希望 IDE 也遵循同一套缩进规则，优先 EditorConfig；如果想把 shfmt 的专属选项集中管理、与项目一起版本化，用 .shfmt.toml；两者冲突时记住 EditorConfig 优先于 TOML。

Q5：它和 shellcheck 是替代关系吗？ A：不是。shfmt 处理格式，shellcheck 侧重静态缺陷检查（引用错误、语法陷阱等），两者互补。常见做法是 CI 里同时跑 shfmt -d . 和 shellcheck，一个管风格，一个管正确性。