1. 改完 settings.xml 依赖反而拉不下来，问题出在哪
Maven 依赖拉取失败这件事，很多人第一反应是网络问题，第二反应是仓库地址写错了。但真正折腾过一下午的人会知道，最坑的情况往往是：配置看起来完全正确，mvn命令也不报语法错误，可依赖就是解析不了，或者明明改了远程仓库地址，本地还是用旧的那份缓存。
我最近就遇到一次。项目里把settings.xml的 mirror 指向了 TaoToken 的统一 API 通道，想着这样团队里所有人的依赖都走同一个出口，Key 也好管理。结果改完之后，mvn clean install直接卡在依赖解析阶段，报了一堆Could not resolve dependencies。更诡异的是，把配置改回去，有些模块能编译，有些还是不行——典型的缓存和配置打架。
先说清楚这篇文章要解决什么：当你的settings.xml里 mirror 或 repository 指向 TaoToken 之后，出现依赖解析失败、缓存不刷新、mvn反复用旧元数据的情况，怎么一步步排查到根因，怎么清理本地仓库，怎么用mvn dependency:resolve验证拉取恢复正常。适合谁看？正在用 Maven 构建 Java 项目、需要统一管理依赖出口、又不想每次改配置都靠删仓库碰运气的开发者。
Maven 的依赖解析其实分两层：一层是本地仓库（默认在~/.m2/repository），一层是远程仓库（由settings.xml和pom.xml共同决定）。本地仓库里存的不只是 jar 包，还有_remote.repositories、*.lastUpdated、maven-metadata-*.xml这些元数据文件。当你换了远程仓库地址，Maven 并不会自动认为"这个包要从新地址重新拉"，它会先看本地有没有，有就直接用。如果本地那份是从旧地址拉的，或者上次拉取失败留下了.lastUpdated标记，Maven 就会认为"这个依赖已经尝试过了，短期内不再重试"，于是你就看到依赖解析失败，但删掉本地对应目录后又好了。
这就是为什么很多人说"缓存问题很讨厌"。它不像语法错误那样直接告诉你哪一行错了，而是表现为各种似是而非的失败。下面我按实际排查顺序，把配置、清理、验证三块拆开讲。
2. TaoToken 前置准备：Key、Base URL 和 Model ID 三件套
在动settings.xml之前，先把 TaoToken 这边的接入信息准备好。不管你是走 Maven 依赖代理，还是后面要接 Claude Code、Cline 这类编码工具，核心都是三样东西：Base URL、API Key、Model ID。这三件套缺一个都跑不通，而且报错信息往往不会直接告诉你缺的是哪个。
Base URL 用https://taotoken.net/api，注意这个地址不带任何查询参数，是纯 API 入口。API Key 需要你去控制台生成，路径是 console 页面里的 api-keys 管理。生成之后复制出来，注意别带多余空格，很多人粘贴时末尾带了个换行，导致认证失败还找不到原因。
Model ID 这块要看你实际用哪个模型。如果你只是想让 Maven 依赖走统一通道，那 Model ID 可能不直接体现在settings.xml里，而是体现在你后续用 TaoToken 做模型对话或编码辅助时的配置中。但如果你是把 TaoToken 当作 Maven 仓库的代理出口，那settings.xml里主要配的是 mirror 的 URL 和认证信息。
这里有个容易混淆的点：TaoToken 的 API 通道和 Maven 仓库代理不是一回事。API 通道是给模型调用用的，Maven 仓库代理是给依赖拉取用的。如果你的场景是"把 settings.xml 的 mirror 指向 TaoToken"，那你要确认 TaoToken 是否提供了 Maven 仓库镜像服务。如果没有，那 mirror 指向一个非 Maven 仓库的地址，必然导致依赖解析失败——这不是缓存问题，是配置方向错了。
所以第一步先确认：你改settings.xml的目的是什么？如果是想让模型调用走 TaoToken，那不该改 Maven 的 mirror，而应该在编码工具（Claude Code、Cline 等）里配 Base URL 和 Key。如果是想让 Maven 依赖走 TaoToken 的仓库代理，那要确认 TaoToken 提供了对应的 Maven 仓库地址。搞混这两件事，后面怎么清缓存都没用。
假设你确认了是要配 Maven 仓库代理，那settings.xml里需要配的是<mirror>或<repository>，加上<server>里的认证信息。下面给可复制的配置片段。
3. 可复制的 settings.xml 配置片段与本地仓库清理命令
先看settings.xml的配置。文件位置通常在~/.m2/settings.xml（Linux/macOS）或C:\Users\你的用户名\.m2\settings.xml（Windows）。如果你用的是 IDE 内置的 Maven，可能指向的是 IDE 配置目录下的 settings.xml，这个要确认清楚，改错文件等于没改。
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> <mirrors> <mirror> <id>taotoken-maven</id> <name>TaoToken Maven Mirror</name> <url>https://taotoken.net/api</url> <mirrorOf>central</mirrorOf> </mirror> </mirrors> <servers> <server> <id>taotoken-maven</id> <username>your-api-key</username> <password></password> </server> </servers> </settings>注意几个关键点。<mirrorOf>central</mirrorOf>表示只镜像 central 仓库，如果你要镜像所有仓库，可以写*，但这样容易把一些私有仓库也劫持了，导致解析失败。<id>要和<server>里的<id>一致，否则认证信息匹配不上，会报 401。<username>填你的 API Key，<password>留空或者也填 Key，具体看 TaoToken 的认证方式。
如果你不是用 mirror，而是用 repository，配置会不一样：
<profiles> <profile> <id>taotoken-repo</id> <repositories> <repository> <id>taotoken-maven</id> <url>https://taotoken.net/api</url> <releases><enabled>true</enabled></releases> <snapshots><enabled>false</enabled></snapshots> </repository> </repositories> </profile> </profiles> <activeProfiles> <activeProfile>taotoken-repo</activeProfile> </activeProfiles>配好之后，别急着跑mvn clean install。先清理本地仓库里可能冲突的缓存。最直接的方式是删掉整个本地仓库，但这样代价太大，所有依赖都要重新拉。更精准的做法是只删掉出问题的依赖目录，以及那些.lastUpdated文件。
清理.lastUpdated文件的命令，Linux/macOS 下：
find ~/.m2/repository -name "*.lastUpdated" -deleteWindows PowerShell 下：
Get-ChildItem -Path "$env:USERPROFILE\.m2\repository" -Recurse -Filter "*.lastUpdated" | Remove-Item -Force如果你确定是某个特定依赖的问题，比如com.example:demo-lib，可以直接删掉对应目录：
rm -rf ~/.m2/repository/com/example/demo-lib删完之后，Maven 下次构建时会重新从远程仓库拉取。但这里有个坑：如果你删了目录但没删.lastUpdated，Maven 可能还是认为"这个依赖最近尝试过，跳过"。所以顺序是先删.lastUpdated，再删依赖目录，或者干脆一起删。
还有一个更彻底的方式，用 Maven 自带的-U参数强制更新：
mvn clean install -U-U会强制检查远程仓库的更新，忽略本地缓存中的"已尝试"标记。但注意，-U不会删除本地已有的 jar 包，它只是强制检查更新。如果本地 jar 包本身是坏的或者不完整，-U也救不了，还是得删目录。
4. 用 mvn dependency:resolve 验证拉取是否恢复
配置改完、缓存清完，怎么确认依赖拉取真的恢复正常了？别直接跑mvn clean install，那个输出太长，出了问题不好定位。用mvn dependency:resolve更聚焦，它只做依赖解析，不编译不打包，输出清晰。
mvn dependency:resolve -U如果一切正常，你会看到类似这样的输出：
[INFO] Scanning for projects... [INFO] [INFO] ----------------------< com.example:demo >----------------------- [INFO] Building demo 1.0-SNAPSHOT [INFO] --------------------------------[ jar ]--------------------------------- [INFO] [INFO] --- maven-dependency-plugin:3.6.0:resolve (default-cli) @ demo --- [INFO] The following files have been resolved: [INFO] org.springframework:spring-core:jar:5.3.30:compile [INFO] org.springframework:spring-context:jar:5.3.30:compile [INFO] ... [INFO] BUILD SUCCESS关键看两点：一是BUILD SUCCESS，二是The following files have been resolved下面列出了所有依赖。如果某个依赖解析失败，会明确告诉你哪个 artifact 找不到，以及尝试了哪些仓库。
如果输出里有Could not resolve dependencies或者Failed to read artifact descriptor，那说明还有问题。这时候看错误信息里提到的仓库地址，确认是不是你配的 TaoToken 地址。如果地址不对，说明settings.xml没生效，可能改错了文件，或者 IDE 用了自己的 settings。
验证单个依赖是否拉取成功，可以用：
mvn dependency:get -Dartifact=org.springframework:spring-core:5.3.30 -U这个命令会直接去远程仓库拉取指定依赖，成功的话会输出BUILD SUCCESS，失败的话会告诉你具体原因。适合用来快速测试某个特定依赖能不能从 TaoToken 拉到。
还有一个实用技巧：用mvn help:effective-settings查看当前生效的 settings 配置。这个命令会把你所有 settings.xml（全局的、用户的、IDE 的）合并后的结果打印出来，你能清楚看到最终生效的 mirror 和 server 是什么。
mvn help:effective-settings如果输出里的 mirror URL 不是你配的 TaoToken 地址，那就说明有更高优先级的配置覆盖了你的修改。常见的是 IDE 自带的 settings.xml，或者M2_HOME/conf/settings.xml里的全局配置。
5. 本篇常见错误排查：401、local proxy failed、reading choices、OAuth
配置和清理都做了，还是失败？下面按真实报错分类排查。
401 Unauthorized：认证失败。检查<server>里的<id>是否和<mirror>的<id>一致，检查 API Key 是否复制完整、有没有多余空格或换行。如果 Key 是对的，确认 TaoToken 的认证方式是 Basic Auth 还是 Bearer Token，settings.xml的<server>默认走 Basic Auth，如果 TaoToken 要求 Bearer，可能需要额外配置或者用其他方式。
local proxy failed / Connection refused：本地代理连接失败。这个报错通常出现在你配了 HTTP 代理但代理没启动，或者代理地址写错。检查settings.xml里有没有<proxies>配置，如果有，确认代理地址和端口是否正确。如果你没配代理但报这个错，可能是环境变量HTTP_PROXY/HTTPS_PROXY在作怪，用echo $HTTP_PROXY确认一下。
reading choices / 解析元数据失败：Maven 在读取maven-metadata.xml时失败，通常是远程仓库返回的内容不是合法的 XML，或者返回了 HTML 错误页。这种情况多半是 mirror URL 指向了一个非 Maven 仓库的地址，比如把 API 地址当成了仓库地址。确认https://taotoken.net/api是否真的提供 Maven 仓库服务，如果不提供，那 mirror 就不该指向它。
OAuth / token 过期：如果你用的是 OAuth 方式的认证，token 过期后会报认证失败。重新生成 API Key，更新settings.xml里的<server>配置。注意 OAuth token 通常有有效期，长期构建的项目要考虑 token 刷新机制。
依赖解析成功但编译报 ClassNotFound：这种不是拉取失败，是拉取到了错误的版本，或者依赖冲突。用mvn dependency:tree查看依赖树，确认实际引入的版本是不是你期望的。如果是版本冲突，用<dependencyManagement>锁定版本。
改了 settings.xml 但完全不生效：确认你改的文件路径。Maven 查找 settings.xml 的顺序是：~/.m2/settings.xml>M2_HOME/conf/settings.xml。IDE 里可能还有自己的配置。用mvn help:effective-settings看最终生效的是哪个。
清理缓存后还是用旧版本：检查pom.xml里有没有<version>写死，或者父 pom 里锁定了版本。另外，SNAPSHOT 版本的更新策略和 release 不同，默认每天检查一次，可以用-U强制更新。
6. 接入文档与 API Key 管理入口
配置改完、验证通过之后，日常维护主要就是 Key 的管理和文档查阅。API Key 在 console 的 api-keys 页面管理，可以生成多个 Key 分配给不同环境，比如开发环境一个、CI 环境一个，方便出问题时快速定位和吊销。
接入文档在 doc 页面，里面有各种工具的配置示例，包括 Claude Code、Cline、Codex 等。如果你后面要把 TaoToken 接到编码工具里，参考 doc 里的配置说明，核心还是那三件套：Base URL 填https://taotoken.net/api，Key 填你生成的 API Key，Model ID 按文档里列出的填。
如果你主要是做长期编码或者 Agent 类任务，可以看 coding-plan 页面，里面有针对这类场景的配置建议。如果只是临时验证某个模型能不能用，模型对话页面可以直接测试。
最后说个实际经验：Maven 缓存问题排查，最有效的顺序是"先确认配置生效，再清缓存，最后验证拉取"。很多人一上来就删仓库，删完发现还是不行，因为根因是配置没生效。用mvn help:effective-settings确认配置，用mvn dependency:resolve -U验证拉取，这两步能省掉大量瞎折腾的时间。
