settings.xml 中 localRepository 不生效需依次检查：配置文件位置（优先用户级 ~/.m2/settings.xml）、路径为绝对路径且无中文/空格/~、IDE 是否覆盖设置、权限与文件系统兼容性、路径末尾不带斜杠。
settings.xml 里 localRepository 不生效？先确认配置位置对不对
Maven 只认两个地方的 settings.xml：用户级（~/.m2/settings.xml）和全局级（$M2_HOME/conf/settings.xml）。它优先用用户级，如果该文件不存在，才 fallback 到全局。很多人改了全局文件却没建用户级文件，结果修改完全不生效。
- 确保你在编辑的是
~/.m2/settings.xml（Windows 是%USERPROFILE%.m2\settings.xml） - 如果该文件不存在，不要只改全局的，要么复制一份到用户目录下再改，要么直接新建
- 修改后无需重启 IDE，但已有导入的 Maven 项目可能需要右键 → “Reload project”（IntelliJ）或刷新依赖（VS Code）
写错 localRepository 路径格式导致 Maven 启动失败
路径必须是绝对路径，且不能包含中文、空格或 shell 特殊字符（如 ~）。Maven 解析时不做任何 shell 展开或 home 替换。
- ✅ 正确：
<localrepository>/Users/you/m2-repo</localrepository> - ❌ 错误：
<localrepository>~/m2-repo</localrepository>（~不展开） - ❌ 错误：
<localrepository>D:\my repo</localrepository>（空格会导致解析中断） - Windows 下推荐用正斜杠或双反斜杠：
D:/m2-repo或D:\m2-repo
改完记得验证：运行 mvn help:effective-settings，检查输出中 localRepository 的值是否是你设的路径。
IDEA / Eclipse / VS Code 仍读旧仓库？检查是否被项目级配置覆盖
有些项目根目录下有 .mvn/maven.config 或 pom.xml 里硬编码了 <localrepository></localrepository>（极少见但存在），或者 IDE 自己缓存了仓库路径。
- IDEA：File → Settings → Build → Build Tools → Maven → Local repository，这里显示的是当前生效路径，它会覆盖
settings.xml中的设置 - Eclipse：Window → Preferences → Maven → User Settings，确认勾选了“Override workspace settings”，并指向你改过的
settings.xml - VS Code：Maven extension 默认读系统级配置，但如果装了多个 JDK/Maven，可能读错
M2_HOME对应的 conf 目录
最稳的验证方式：终端进任意空目录，执行 mvn archetype:generate -DgroupId=test -DartifactId=test-app -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false，然后看下载的依赖实际落到了哪个目录——这才是真实生效的 localRepository。
改完路径后依赖下载失败或校验报错？留意权限与迁移问题
新路径如果在 NTFS/exFAT/U 盘等非默认分区，可能遇到权限或文件系统兼容性问题：
- Linux/macOS：确保目标目录可读写，
chmod -R u+rwX /path/to/m2-repo - Windows：避免放在 OneDrive/Google Drive 同步目录里，这些服务会锁文件，导致 Maven 写入失败或 checksum 校验不通过
-
不要手动剪切旧仓库过去：直接改路径后首次构建会重新下载，旧仓库留着无害；若想迁移，用
rsync -av --exclude='<em>.lastUpdated' ~/.m2/repository/ /new/path/repository/</em>（Linux/macOS）或 robocopy（Windows），但跳过所有.lastUpdated文件，否则 Maven 会拒绝使用缓存
最容易被忽略的一点：Maven 3.9+ 对 localRepository 路径合法性检查更严格，如果路径末尾带斜杠（如 /path/to/repo/），某些版本会静默截断或报错——务必保证路径不以 / 结尾。
