Maven Central 与 NuGet 下载失败：超时、NU1301 和镜像怎么选

Java 项目执行 mvn -U clean package 时，日志停在 Could not transfer artifact，后面跟着 from/to central（https://repo.maven.apache.org/maven2）：Connect timed out。换 .NET 解决方案，dotnet restore 第一行就是 NU1301：Unable to load the service index for source https://api.nuget.org/v3/index.json。两种报错都发生在「还没开始编译」之前，包管理器连不上中央仓库。

国内网络访问 Maven Central 与 nuget.org 经常被重置或超时，也有人把镜像写进 settings.xml 之后，快照版本和校验和开始对不上。下面先把访问官方源的线路准备好，再决定要不要用镜像，最后用一条命令确认解析的是你以为的那个仓库。仓库地址和错误码以当前 Maven、NuGet 版本文案为准。

官方源、镜像和缓存分别管什么

镜像不是官方源的别名。它晚同步时，你会看到本地以为的版本在镜像上不存在，报错却写着找不到构件。排错时先保证能直接打开官方索引，再谈加速。

从超时到能还原：分步操作

• 第一步：先把网络线路准备好，再跑构建。安装刺猬VPN，用自定义用户名和密码匿名注册，不需要邮箱和手机号。连上后再执行 mvn 或 dotnet restore，让 repo.maven.apache.org、repo1.maven.org 与 api.nuget.org 走同一条线路。免费节点永久免费、不限流量、不限速，适合先确认索引能否打开。
• 第二步：浏览器直接打开 https://repo.maven.apache.org/maven2/ 和 https://api.nuget.org/v3/index.json。前者应看到目录或仓库页，后者应返回一段 JSON。打不开就换同地区节点，不要先改镜像。
• 第三步：确认构建工具没有残留错误镜像。Maven 看用户目录下的 .m2/settings.xml，搜索 mirrorOf。若 mirrorOf 写成 *，所有请求包括插件仓库都会被送去镜像。NuGet 在命令行执行 dotnet nuget list source，看 nuget.org 是否被禁用。
• 第四步：临时绕过镜像做一次官方还原。把有问题的 mirror 整段注释掉，或把 nuget.org 重新设为启用，然后在项目根目录执行 mvn -U dependency:resolve 或 dotnet restore --force。-U 会强制更新快照与元数据。
• 第五步：若日志变成 PKIX path building failed 或 SunCertPathBuilderException，这是证书链而不是超时。核对系统时间、公司代理是否替换了证书，以及 JAVA_HOME 用的是哪套信任库。时间不对时先校正时钟再重试。
• 第六步：NuGet 在 Visual Studio 里还要看图形界面：工具、选项、NuGet 包管理器、包源。列表里 nuget.org 的地址应是 https://api.nuget.org/v3/index.json。解决方案级的 nuget.config 会覆盖用户级配置，以离项目更近的那份为准。
• 第七步：还原成功后抽查一个依赖的版本是否与 pom 或项目文件一致。镜像场景下再比对文件大小或校验和，不一致就删掉本地缓存里的该构件后改回官方源重下。
• 第八步：团队要长期使用镜像时，把 mirror 的 url、mirrorOf 范围写进文档，并规定快照与插件仓库是否例外。个人机器先能走官方源，再按仓库域名做分流，避免全局强制镜像。

按报错原文往下查

• Connect timed out 或 Connection reset：官方主机没连通。先用浏览器打开仓库根地址，再换节点。不要把超时误判成版本号写错。
• NU1301：服务索引下载失败。dotnet nuget list source 确认 URL，并检查项目里的 nuget.config 有没有把 nuget.org 清掉。
• NU1101：索引通了，但这个 id 在当前源里没有。核对包名大小写、是否只存在于私有源、预发布版本有没有加源。
• Could not find artifact 或 Non-resolvable parent POM：父 POM 的仓库地址不可达，或镜像没有同步父构件。先让 central 直连再解析父 POM。
• PKIX path building failed：Java 不信任对方证书。检查系统时间、是否有拦截证书的安全软件，以及 settings.xml 里错误的 https 代理。
• 还原很慢但最终成功：元数据在反复拉取。确认没有两个源同时提供同一包导致来回比较，必要时禁用重复源。
• 只有 CI 失败、本机成功：CI 没有同一条出网线路，或镜像用了内网地址。在 CI 上单独打开 index.json 看返回。

官方源和镜像怎么选

刺猬VPN自身不对账号设速率上限。构建快慢还取决于仓库响应和依赖体积。实际可用性取决于当前网络环境。需要发布给别人用的构件，优先官方源。镜像只适合能接受延迟、并且会核对校验和的团队。

settings.xml 与 NuGet.Config 对照

Maven 的用户级文件在主目录 .m2/settings.xml。镜像写成 mirror 元素：id 自定，url 填镜像地址，mirrorOf 不要轻易写成星号。星号表示连插件仓库也改道。只想镜像 central 时，mirrorOf 写 central。改完执行 mvn help:effective-settings，看生效结果里还有没有旧 url。

NuGet 用户级配置在系统的 NuGet 目录，项目级是仓库根下的 nuget.config。packageSources 里可以有多条。清除源用 dotnet nuget remove source，添加官方源用 dotnet nuget add source，地址为 https://api.nuget.org/v3/index.json。Visual Studio 的包源界面和命令行必须一致，否则界面还原成功、脚本还原失败。

和其他包管理器的分工

Maven 与 NuGet 只是 JVM 和 .NET 这两条线。npm、PyPI、Docker 镜像的超时要用另一套配置文件，集中说明见 开发包仓库打不开怎么办。Homebrew、Go 模块和 Rust crates 的代理变量写法不同，对照见 Homebrew、Go 与 Rust 代理。

不要把一种语言的镜像地址抄到另一种工具里。排错顺序始终是：浏览器能否打开索引、配置文件是否改道、缓存里的校验和是否匹配。

常见报错速查表

缓存、多模块和私有源怎么一起排

超时中断后，Maven 会在用户目录 .m2/repository 里留下带 lastUpdated 的标记。下次构建看到标记，就不再认真请求中央仓库，日志仍像是找不到构件。只删除该构件那一层文件夹，不要清空整个 repository，否则所有依赖都要重下。删完执行 mvn -U dependency:resolve。多模块工程要进入报错的那个子目录再跑，父工程的有效配置看不到子模块 pom 里另写的仓库。

私有源和 nuget.org 同时存在时，NU1101 可能只是包在私有源、而还原顺序先问了公共源。在项目的 nuget.config 里用 packageSourceMapping 把内部包名前缀绑到私有源，其余再落到 nuget.org。不映射时，两个源都会被问一遍，私有源超时会拖住整个还原，看起来像官方源坏了。

插件和依赖不是同一个仓库坐标。只给依赖配了镜像、插件仍走 repo.maven.apache.org 时，依赖成功、插件下载超时会交替出现。effective-settings 里把 pluginRepositories 也看一遍。CI 使用的 settings 文件要用 -s 显式指定，否则开发机用户目录里的配置不会出现在构建机上。

核对校验和时，以中央仓库页面上该版本的文件大小为对照，不要只看本机 jar 能不能被解压。能解压只说明文件没截断，不能说明你拿到的是发布者上传的那一份。镜像字节不一致就改回官方源重下这一份，并在团队说明里写上哪一天镜像落后过。

个人电脑能还原、持续集成不能还原，几乎都是配置没进仓库。把生效的设置文件提交进去，构建时用参数显式加载，同事克隆后才会得到和你一样的解析结果。只在自己的用户目录里改过，流水线仍会超时，日志却像是依赖坐标写错了。

公司内网构件必须直连、中央仓库需要线路时，用按域名的分流把两类地址分开，不要把整台机器的流量都送进隧道，也不要靠一份把所有仓库都改道的镜像硬合并。发布给外部使用的版本以中央仓库上的文件为准，内部快照可以留在私有源，但要在说明里写清哪一类走哪一边。还原日志里如果交替出现超时和找不到构件，先把镜像整段注释掉再跑一遍，确认官方源本身是通的，再决定镜像还要不要加回去。不要在同一次失败里同时改坐标、改镜像、改线路，否则下次成功时不知道是哪一项起了作用。版本号在私有源和中央仓库各有一份时，以构建文件里写明的源为准，不要让两个源靠谁先响应来决定用哪一份。坐标写错和网络超时要分两次试，先保持坐标不动，只恢复官方源。把这次成功的命令和配置文件位置写进项目说明，下次超时先重复这一条，而不是重新搜索镜像地址。依赖能下、插件不能下时，分开看两类仓库。

高频问答

• 问：阿里云或其他镜像能不能代替官方源？答：能减轻压力，但会有同步延迟。发布构建仍建议能直连中央仓库，并用校验和核对。
• 问：settings.xml 放哪？答：当前用户主目录下的 .m2 文件夹。全局 settings 在 Maven 安装目录的 conf 里，用户级优先。
• 问：为什么网页能开、命令行超时？答：命令行可能走了另一套代理或镜像。用 mvn help:effective-settings 看生效仓库。
• 问：NU1301 和 NU1101 怎么区分？答：1301 是索引没下来，1101 是索引在但没有这个包。
• 问：要不要把 Maven 进程单独做代理？答：客户端没有按应用勾选的代理列表。需要区分内外网时，用按域名的智能分流，让仓库域名走线路、内网地址不走。
• 问：免费节点够不够拉依赖？答：够用来验证索引和少量包。大批量还原更适合时长套餐，期间不限流量、不限速。

可复现构建时记住的顺序

Maven Central 超时、NuGet 的 NU1301、PKIX 证书失败，分别是连通、源配置和证书三件事。先连上线路并用浏览器打开两个索引，再注释 mirrorOf 为星号的镜像，最后强制还原。校验和不一致就删缓存，不要在错误构件上继续编译。

刺猬VPN采用 HTTPS+AES 加密传输。注册只需自定义用户名和密码，不需要邮箱和手机号，找回密码凭支付订单记录。免费节点永久免费、不限流量、不限速。时长套餐在有效期内不限流量、不限速，一个账号可多设备同时在线。仓库是否可访问取决于当前网络环境，镜像同步策略以镜像站说明为准。