.mvnw脚本执行失败，提示“Permission denied”如何解决？

Question

`.mvnw` 脚本执行时报 “Permission denied”，本质是 Linux/macOS 下文件无执行权限所致。该脚本由 Maven Wrapper 生成，默认不带 `x` 权限（Windows 因不依赖 shell 权限故无此问题）。解决方法：在项目根目录运行 `chmod +x .mvnw`，赋予可执行权限；若同时需支持 `./mvnw.cmd`（Windows）以外的环境，建议一并执行 `chmod +x .mvnw` 和 `chmod +x .mvn/wrapper/maven-wrapper.jar`（虽 jar 不需执行权，但部分旧版 wrapper 会误调用）。验证：`ls -l .mvnw` 应显示 `-rwxr-xr-x`。另注意：若使用 WSL 或容器环境，确保文件系统未挂载为 `noexec`；Git 克隆时权限丢失，可配置 `git config core.filemode true` 并重新检出。根本预防：团队统一启用 `git update-index --chmod=+x .mvnw` 提交权限变更。

Answer 1

```html

一、现象层：典型报错与环境复现

在 Linux/macOS 终端执行 ./.mvnw clean install 时，终端抛出：
bash: ./.mvnw: Permission denied。该错误不出现于 Windows 原生 CMD/PowerShell（因依赖 .mvnw.cmd 批处理），却高频见于 CI/CD 流水线（Jenkins Agent、GitHub Actions Ubuntu runner）、Docker 构建阶段及 WSL2 开发环境。

二、机制层：为什么 .mvnw 默认无执行权限？

• Maven Wrapper（maven-wrapper.jar）由 mvn wrapper:wrapper 插件生成，其核心脚本 .mvnw 是 POSIX shell 脚本（shebang #!/bin/sh），但 Maven 官方构建逻辑未调用 chmod +x 写入文件系统权限位；
• Git 默认仅跟踪内容哈希，不持久化 Unix 权限位（除非显式启用 core.filemode）；
• Windows 文件系统（NTFS）无 POSIX 权限模型，克隆至 macOS/Linux 时，Git 无法还原执行位 —— 这是跨平台协作的“隐性断点”。

三、验证层：三步定位根因

1. ls -l .mvnw → 观察输出是否为 -rw-r--r--（缺失 x）；
2. file .mvnw → 确认类型为 POSIX shell script, ASCII text executable；
3. mount | grep "$(pwd)"（Linux/macOS）或 cat /proc/mounts | grep noexec → 排查是否挂载了 noexec 选项（常见于容器 volume 或 WSL 配置不当）。

四、解决层：即时修复与兼容性加固

操作	命令	说明
基础修复	chmod +x .mvnw	赋予脚本执行权限（必需）
旧版兼容	chmod +x .mvn/wrapper/maven-wrapper.jar	规避 v0.5.x 以下 Wrapper 的 exec 误调用（防御性操作）

五、预防层：从个人习惯到团队规范

单点修复治标，体系化治理治本：

• 本地 Git 配置：git config --global core.filemode true，再执行 git rm --cached .mvnw && git add .mvnw && git commit -m "chore: persist .mvnw exec bit"；
• 团队统一提交：git update-index --chmod=+x .mvnw（推荐在 CI 流水线 Pre-Commit Hook 中自动化校验）；
• Dockerfile 建议：RUN chmod +x .mvnw && ./mvnw -N io.takari:maven-wrapper:0.5.6:wrapper，避免镜像构建阶段权限丢失。

六、进阶洞察：WSL/容器特殊场景深度分析

graph TD A[执行 .mvnw 失败] --> B{检查挂载选项} B -->|noexec| C[重新 mount -o remount,exec /path/to/repo] B -->|exec 但仍失败| D[检查 Windows 主机侧文件属性
是否勾选“只读”或“隐藏”] B -->|正常| E[确认 .mvnw 是否被 Windows 编辑器
意外转为 DOS 换行符 CRLF] E --> F[用 dos2unix .mvnw 修复]

七、工程实践建议：CI/CD 流水线防御性检查

在 GitHub Actions 的 .github/workflows/build.yml 中嵌入权限自检步骤：

- name: Validate Maven Wrapper permissions
  run: |
    if [[ ! -x ".mvnw" ]]; then
      echo "ERROR: .mvnw is not executable"
      ls -l .mvnw
      exit 1
    fi

八、延伸思考：为何不直接修改 Wrapper 源码？

Apache Maven Wrapper 项目（github.com/apache/maven-wrapper）明确将权限设置视为“用户环境责任”，因其需兼容：
• NFS/SMB 共享存储（无 chmod 支持）
• Git LFS 管理的大文件仓库
• Air-gapped 离线环境（无法联网下载带权限的预编译脚本）
——这体现了开源工具对部署场景多样性的审慎权衡。

九、版本演进追踪：关键变更节点

• v0.5.6+：Wrapper 启动逻辑改用 java -jar 显式调用，.mvn/wrapper/maven-wrapper.jar 不再需要 +x（但保留无害）；
• v1.0.0-rc1（2023）：引入 --force 参数强制重写 .mvnw 并自动设权（实验性）；
• 当前最佳实践：使用 mvn -N io.takari:maven-wrapper:1.0.0:wrapper -Dmaven=3.9.6 生成新 wrapper。

十、终极检查清单（DevOps 团队可直接导入 SOP）

1. ✅ ls -l .mvnw 输出含 x（如 -rwxr-xr-x）
2. ✅ git ls-files --stage .mvnw | cut -f1 返回 100755（非 100644）
3. ✅ docker run --rm -v $(pwd):/workspace -w /workspace ubuntu:22.04 ./mvnw -v | head -1 成功输出版本
4. ✅ GitHub Actions 日志中无 Permission denied 且 mvnw 步骤耗时 ≤ 3s（排除反复下载）
5. ✅ 团队新成员首次 git clone 后无需手动 chmod 即可运行

```