mvdan/shfmt

sh Docker镜像文档

镜像概述和主要用途

sh Docker镜像是基于https://github.com/mvdan/sh%E9%A1%B9%E7%9B%AE%E7%9A%84%E5%AE%98%E6%96%B9%E9%95%9C%E5%83%8F%EF%BC%8C%E4%B8%BB%E8%A6%81%E5%8C%85%E5%90%AB%60shfmt%60%E5%B7%A5%E5%85%B7%E3%80%82%60shfmt%60%E6%98%AF%E4%B8%80%E6%AC%BE%E5%8A%9F%E8%83%BD%E5%BC%BA%E5%A4%A7%E7%9A%84shell%E7%A8%8B%E5%BA%8F%E6%A0%BC%E5%BC%8F%E5%8C%96%E5%99%A8%EF%BC%8C%E6%94%AF%E6%8C%81POSIX Shell、Bash和mksh等多种shell语法。该镜像旨在提供便捷的容器化部署方式，帮助用户在各类环境中快速实现shell脚本的格式化、语法检查和风格统一，适用于开发、CI/CD及团队协作场景。

核心功能和特性

• 多语法支持：兼容POSIX Shell、Bash和mksh语法标准，满足不同shell环境的格式化需求。
• 轻量级部署：提供标准和-alpine两种镜像变体，基于Alpine Linux的变体体积更小，资源占用低。
• 便捷集成：无需本地安装依赖，通过Docker即可快速运行，适合集成到开发环境和自动化流程。
• 语法检查能力：在格式化过程中可检测部分常见语法错误，如关联数组索引格式问题、表达式歧义等。
• 跨平台兼容：支持多种操作系统和架构，可在Linux、macOS等环境中稳定运行。

使用场景和适用范围

• 开发环境：开发人员本地格式化shell脚本，确保代码风格一致。
• CI/CD流程：集成到持续集成/部署 pipeline，自动检查并格式化提交的shell脚本。
• 团队协作：作为团队编码规范工具，统一shell脚本格式，减少代码评审中的风格争议。
• 学习教育：帮助理解规范的shell语法结构，辅助学习shell编程。

详细使用方法和配置说明

Docker镜像构建

如需构建自定义镜像，执行以下命令：

bash
docker build -t my-shfmt:tag -f cmd/shfmt/Dockerfile .

Docker镜像使用

基本运行命令

bash
docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/mnt" -w /mnt docker.xuanyuan.run/my-shfmt:tag <shfmt参数>

参数说明：

• --rm：容器退出后自动删除，避免残留容器实例。
• -u "$(id -u):$(id -g)"：指定当前用户ID和组ID，防止生成的文件权限异常。
• -v "$PWD:/mnt"：将当前工作目录挂载到容器内/mnt目录，使容器可访问本地脚本文件。
• -w /mnt：设置容器工作目录为/mnt，即挂载的本地目录。
• <shfmt参数>：shfmt工具的格式化参数（详见下文示例）。

常用示例

1. 查看需要格式化的文件列表：

   bash
   docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/mnt" -w /mnt docker.xuanyuan.run/my-shfmt:tag -l *.sh
   

2. 格式化并覆盖文件：

   bash
   docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/mnt" -w /mnt docker.xuanyuan.run/my-shfmt:tag -w script.sh
   

3. 指定缩进为4个空格：

   bash
   docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/mnt" -w /mnt docker.xuanyuan.run/my-shfmt:tag -i 4 -w script.sh
   

镜像标签说明

• latest：最新开发版本。
• v3：最新稳定版本（主版本3系列）。
• v3.x.y（如v3.5.1）：特定版本标签。
• -alpine后缀：基于Alpine Linux的轻量级变体（如v3-alpine）。

注意事项

语法解析限制

1. Bash关联数组索引：必须使用引号包裹索引，否则解析器会将其视为算术表达式导致错误。

   sh
   # 错误示例
   ${array[spaced string]}  # 解析错误：不是有效的算术运算符
   ${array[weird!key]}      # 解析错误：未匹配的!符号
   
   # 正确示例
   ${array["spaced string"]}
   ${array["weird!key"]}
   

2. $((和((歧义：不支持$((和((的歧义解析，POSIX规范建议通过空格区分$( (。

   sh
   # 错误示例
   $((foo); (bar))  # 解析错误：未匹配的)符号
   
   # 正确示例
   $( (foo); (bar) )
   

3. 关键字解析：export、let、declare被解析为关键字，支持静态语法树构建，但不支持declare {a,b}=c类扩展语法。

镜像内容说明

Docker镜像仅包含shfmt工具，如需使用项目其他组件（如gosh解释器），需通过其他方式安装。

相关资源

• 项目主页：https://github.com/mvdan/sh
• shfmt文档：https://github.com/mvdan/sh/blob/master/cmd/shfmt/shfmt.1.scd
• 支持的包管理器：Alpine、Arch、Debian、Fedora、Homebrew、NixOS等（详见项目文档）