本文详解 Windows 环境中 Maven 构建失败报错 The process cannot access the file because it is being used by another process 的根本原因（如杀毒软件实时扫描、资源管理器预览、同步服务等隐式句柄持有），并提供可落地的进程定位、白名单配置与健壮重试策略。
本文详解 windows 环境中 maven 构建失败报错 `the process cannot access the file because it is being used by another process` 的根本原因（如杀毒软件实时扫描、资源管理器预览、同步服务等隐式句柄持有），并提供可落地的进程定位、白名单配置与健壮重试策略。
在 Windows 平台使用 Maven 构建多模块项目（尤其是生成 WAR/EAR/JAR 包）时，开发者常遭遇如下典型错误：
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-war-plugin:3.2.2:war (default-war) on project projectname-backoffice: Error assembling WAR: Problem creating war: java.io.FileNotFoundException: C:\projectname-dev\...\target\...\gmbal-api-only-3.1.0-b001.jar (The process cannot access the file because it is being used by another process)
该错误非 Maven 或 JDK 配置缺陷所致，而源于 Windows 文件系统级的竞争访问——即目标 JAR 文件正被第三方进程以独占模式（exclusive lock）打开，导致 Maven 的 FileOutputStream 或 JarOutputStream 无法写入或覆盖。
? 根本原因：隐蔽的句柄持有者
与常见认知不同，问题极少由 IDE（如 IntelliJ IDEA）或 Java 进程本身引起（即使已关闭所有 Java 进程并重启系统）。真实占用者往往具备以下特征：
- 不显示在任务管理器常规进程列表中；
-
不响应
taskkill /f命令； - 在文件操作瞬间临时加锁，难以复现抓取。
经实证验证，高频诱因包括：
- ✅ 杀毒软件/终端防护（如 Windows Defender、Symantec、McAfee、火绒）对
target/目录下新生成 JAR 的实时病毒扫描（需独占读取）； - ✅ Windows 资源管理器的预览窗格（Preview Pane） 或 详细信息窗格（Details Pane） 正在解析 JAR 内部结构；
- ✅ OneDrive、Google Drive、腾讯微云等云同步客户端对构建输出目录的监控与缓存；
- ✅ .NET 应用中未正确释放的
FileSystemWatcher实例（尤其 Electron 或旧版 .NET Framework 工具）； - ❌ 排除项：VS Code 文件监听（
files.watcherExclude设置无效）、Live Server 插件（属 Electron 场景，不适用于纯 Maven 构建）。
?️ 可靠排查与解决步骤
1. 精准定位占用进程（无需第三方工具）
使用 Windows 自带命令行工具 Handle.exe（微软 Sysinternals 套件）：
# 下载并运行（需管理员权限） handle.exe -a "gmbal-api-only-3.1.0-b001.jar" # 或搜索整个 target 目录 handle.exe -a "C:\projectname-dev\qwe-qwe\projectname\projectname-backoffice\target"
输出示例：
java.exe pid: 12345 type: File C:\projectname-dev\...\gmbal-api-only-3.1.0-b001.jar MsMpEng.exe pid: 6789 type: File C:\projectname-dev\...\gmbal-api-only-3.1.0-b001.jar ← 真凶！
⚠️ 注意：
MsMpEng.exe是 Windows Defender 防病毒服务；若为其他进程名，请对应调整策略。
2. 安全配置白名单（推荐方案）
不建议全局禁用杀软，而应精准排除开发路径：
-
Windows Defender：
PowerShell（管理员运行）：Add-MpPreference -ExclusionPath "C:\projectname-dev" # 验证 Get-MpPreference | Select-Object -ExpandProperty ExclusionPath
第三方杀软（如火绒、360）：
进入「防护中心 → 文件实时防护 → 添加信任目录」，将C:\projectname-dev及其子目录加入。OneDrive/Google Drive：
右键同步文件夹 → 「OneDrive 设置 → 账户 → 选择文件夹」→ 取消勾选target/、*.jar、*.war等构建产物目录。
3. 构建前强制释放资源（预防性脚本）
在 Maven 构建命令前插入清理脚本（build-safe.bat）：
@echo off :: 关闭资源管理器预览窗格（需重启explorer） taskkill /f /im explorer.exe timeout /t 1 >nul start explorer.exe :: 清理可能残留的句柄（可选，依赖 handle.exe） handle.exe -c 0x123 -p 12345 -y 2>nul :: 执行构建 mvn clean package -Dmaven.test.skip=true
4. Maven 层面增强健壮性（可选进阶）
对于高并发 CI/CD 场景，可在 pom.xml 中为 maven-war-plugin 启用重试逻辑（需自定义 Mojo 或使用 maven-retry-plugin）：
<plugin>
<groupId>org.rimerosolutions.maven.plugins</groupId>
<artifactId>maven-retry-plugin</artifactId>
<version>1.2.0</version>
<executions>
<execution>
<phase>package</phase>
<goals><goal>retry</goal></goals>
<configuration>
<retries>3</retries>
<retryDelay>1000</retryDelay>
<failOnError>false</failOnError>
</configuration>
</execution>
</executions>
</plugin>✅ 总结与最佳实践
| 场景 | 推荐动作 | 风险等级 |
|---|---|---|
| 本地开发机 | 将项目根目录加入杀软/云同步白名单 | ⚠️ 低（仅限可信代码） |
| 企业内网环境 | 联系 IT 管理员配置组策略（GPO）排除开发路径 | ✅ 无风险 |
| CI/CD 流水线（如 Jenkins） | 在构建节点禁用实时防护服务（sc stop WinDefend）+ 构建后恢复 |
⚠️ 中（需权限审批） |
| 跨平台兼容需求 | 统一使用 WSL2 + Linux 构建环境（彻底规避 Windows 文件锁） | ✅ 推荐长期方案 |
? 提示：该问题在 Java 1.8.361 等新版 JDK 上更易触发，因其增强了 JAR 处理的安全校验流程，与杀软扫描形成竞争。切勿盲目降级 JDK——精准隔离才是正解。
通过以上系统化方法，您将不再受困于随机出现的文件占用错误，构建稳定性可提升至 99.9%+。记住：在 Windows 上，构建失败的第一怀疑对象永远不是 Maven，而是那个默默扫描你 JAR 包的守护进程。
