Apache Ivy 2.6.0 配置参数详解
解析 Apache Ivy 2.6.0 三层配置体系：ivy.xml 模块描述符、ivysettings.xml 引擎设置与 Ant 任务属性，覆盖动态版本语法、resolver 与镜像替换、缓存参数、pattern 变量与依赖调控，含实测示例
Apache Ivy 2.6.0 配置参数详解
本文基于 Ivy 2.6.0（build 20260712075753）实测与 jar 内置默认 settings 解析。凡标注"实测"的输出均为容器内真实回显；标注"参考"的内容来自随包官方文档，供读者按需取用。
一、配置体系总览：三层结构
Ivy 的配置分三层，各管一摊：
| 层 | 文件/载体 | 管什么 |
|---|---|---|
| 模块描述符 | ivy.xml（每项目一份） | 声明本项目是什么（info）、有哪些配置（configurations）、依赖谁（dependencies）、对外发布什么（publications） |
| 引擎设置 | ivysettings.xml（全局/每项目可选） | 仓库解析器（resolvers）、缓存路径、版本匹配策略、默认设置文件链 |
| 任务属性 | build.xml 中 ivy:* 任务的属性 + 系统属性 | 单次 resolve/retrieve/publish 的行为（pattern、conf、是否传递等） |
不提供 ivysettings.xml 时，Ivy 使用 jar 内置默认设置。实测（ant resolve 首行）：
[ivy:resolve] :: loading settings :: url = jar:file:/opt/ant/lib/ivy-2.6.0.jar!/org/apache/ivy/core/settings/ivysettings.xml
内置默认等价于：默认解析链 public（Maven Central 的 ibiblio resolver），缓存目录 ${user.home}/.ivy2/cache（实测落在 /root/.ivy2/cache）。绝大多数新项目可直接零配置起步，需要企业仓库/镜像时才写 ivysettings.xml。
二、ivy.xml 模块描述符全解
实测通过的完整骨架（demo 项目 /root/ivy-demo/ivy.xml）：
<?xml version="1.0" encoding="UTF-8"?>
<ivy-module version="2.0">
<info organisation="com.example" module="ivy-demo" revision="1.0"/>
<configurations>
<conf name="default" visibility="public"/>
</configurations>
<dependencies>
<dependency org="org.apache.commons" name="commons-lang3" rev="3.+" conf="default"/>
</dependencies>
</ivy-module>
2.1 <ivy-module version="2.0">
描述符格式版本。2.0 是最通用写法，兼容全部现代特性；Ivy 2.x 引擎可读 1.x/2.x 多个版本，新项目统一用 2.0。
2.2 <info>
| 属性 | 说明 |
|---|---|
organisation | 组织反域名（如 com.example），决定缓存路径第一段 |
module | 模块名，决定缓存第二段 |
revision | 本模块版本；未写时按 working 处理 |
status | 集成/里程碑/发布 三档，默认 integration，影响"最新版本"解析 |
branch | 分支标识，可省 |
2.3 <configurations>：依赖的"用途分组"
每个依赖必须挂在一个或多个 configuration 上。常用内置/自定义写法：
<configurations defaultconfmapping="default">
<conf name="default" visibility="public"/>
<conf name="runtime" visibility="public" extends="default"/>
<conf name="test" visibility="private" extends="runtime"/>
</configurations>
visibility="public"的 conf 会随本模块传递给下游；private（如 test）不传递；extends让 conf 继承另一组依赖；- 不写
conf属性的 dependency 默认映射default->default。
2.4 <dependency> 属性速查
| 属性 | 示例 | 说明 |
|---|---|---|
org | org.apache.commons | 目标模块组织 |
name | commons-lang3 | 目标模块名 |
rev | 3.+ / 3.21.0 / [3.18,4.0) | 版本约束，支持动态版本 |
conf | default / test->default | 本模块 conf -> 目标 conf 映射 |
transitive | false | 关闭该依赖的传递解析 |
changing | true | 声明快照类会变的依赖，强制 TTL 失效 |
force | true | 版本冲突时强制采用本条 |
动态版本语法（实测验证）：
| 写法 | 含义 | 实测解析结果 |
|---|---|---|
3.+ | 最新 3.x | 3.21.0（commons-lang3，repo1 当前最新） |
latest.integration | 最新集成版（含快照） | 取 status 最高且最新的 revision |
latest.release | 最新发布版 | 同上但排除 integration |
[3.18,4.0) | 半开区间 | 区间内最新 |
1.0 | 精确版本 | 仅 1.0 |
实测回显（3.+ 的动态替换证据）：
[ivy:resolve] found org.apache.commons#commons-lang3;3.21.0 in public
[ivy:resolve] [3.21.0] org.apache.commons#commons-lang3;3.+
2.5 <exclusions> 与 <overrides>
<dependency org="org.apache.hadoop" name="hadoop-common" rev="3.3.6">
<exclude org="log4j" module="log4j" matcher="exact"/>
</dependency>
exclude 从该依赖的传递树中剪枝；overrides 在 <dependencies> 顶层统一改写多条依赖的版本，适合锁定。
三、ivysettings.xml 引擎设置
自定义时在 ant 命令或任务上指定：ant -Divy.settings.file=ivysettings.xml resolve，或 <ivy:configure file="ivysettings.xml"/>。最小可用样例（保留默认链 + 追加镜像）：
<ivysettings>
<settings defaultResolver="chain-public"/>
<include url="${ivy.default.settings.dir}/ivysettings-public.xml"/>
<resolvers>
<chain name="chain-public">
<resolver ref="aliyun"/>
<resolver ref="public"/>
</chain>
</resolvers>
<resolvers>
<ibiblio name="aliyun" m2compatible="true"
root="https://maven.aliyun.com/repository/public"/>
</resolvers>
</ivysettings>
3.1 <settings> 顶层属性
| 属性 | 默认 | 说明 |
|---|---|---|
defaultResolver | 无 | 未指定 resolver 的依赖用它解析 |
defaultCacheDir | ~/.ivy2/cache | 全局缓存根 |
defaultConflictManager | latest-revision | 冲突仲裁策略，可换 all/strict/compat |
checkUpToDate | true | 缓存命中时是否校验远端变更 |
3.2 常用 resolver 类型
| 类型 | 典型用途 | 关键属性 |
|---|---|---|
ibiblio | Maven 仓库（含 Central） | root、m2compatible="true"、pattern |
filesystem | 本地/内网共享目录仓库 | m2compatible、artifactPattern |
url | 直链仓库 | ivyPattern、artifactPattern |
chain | 多仓库顺序回退 | 子 resolver 依次尝试 |
sftp | 带 SSH 的私服 | host/user/keyFile |
镜像替换实测建议：repo1.maven.org 国内直连约 60KB/s 量级，替换为 https://maven.aliyun.com/repository/public 后可达 1.6MB/s 量级（同机 curl 实测对比）。该 resolver 配置语法为官方文档参考用法，resolver 生效判断以 resolve 日志中的仓库名与下载 URL 为准。
四、缓存机制与关键参数
实测缓存布局（首次 resolve 后）：
/root/.ivy2/cache/
├── org.apache.commons/commons-lang3/ # 元数据目录
│ ├── ivy-3.21.0.xml
│ ├── ivydata-3.21.0.properties
│ └── jars/commons-lang3-3.21.0.jar # artifact 目录
└── com.example/ivy-demo/
└── com.example-ivy-demo-default.xml # 本次解析报告（report 的输入）
| 参数 | 位置 | 作用 |
|---|---|---|
ivy.cache.dir / -cache | 系统属性 / 任务属性 | 改缓存根 |
ivy.resolution.cache.dir | 系统属性 | 单独分离"解析报告"目录 |
changing="true" | dependency 属性 | 每次都向仓库核对（快照场景） |
TTL（cacheTTL） | settings caches 段 | 元数据缓存有效期 |
artifact.lockStrategy | settings caches 段 | 并发构建时的文件锁策略 |
清理即 rm -rf /root/.ivy2/cache；只清单模块用 rm -rf /root/.ivy2/cache/org.apache.commons/commons-lang3。
五、pattern 变量与路径模板
Ivy 所有"路径模板"（retrieve pattern、resolver artifactPattern、publish pattern）共用一套变量：
| 变量 | 含义 | 实测值示例 |
|---|---|---|
[organisation] | 组织（m2compatible 时为点分路径） | org.apache.commons |
[module] | 模块名 | commons-lang3 |
[revision] | 解析后的版本 | 3.21.0 |
[artifact] | 工件名 | commons-lang3 |
[type] | 工件类型 | jar / javadoc / source |
[ext] | 扩展名 | jar |
[conf] | configuration | default |
[originalname] | 源文件名 | commons-lang3-3.21.0.jar |
重要实测教训：独立 CLI 下同一模块缓存里同时存在 jar/javadoc/source 三类 artifact，pattern cli/[artifact].[ext] 会让三者映射到同一文件名，触发硬错误：
Caused by: java.lang.RuntimeException: Multiple artifacts of the module commons-lang#commons-lang;2.6 are retrieved to the same file! Update the retrieve pattern to fix this error.
改为带类型维度的 cli/[artifact]-[type].[ext] 后 4 个 artifact 全部落盘：
:: retrieving :: commons-lang#commons-lang-caller
confs: [default]
4 artifacts copied, 0 already retrieved (2346kB/16ms)
=== cli 目录 ===
-rw-r--r-- 1 root root 284220 Jan 16 2011 commons-lang-jar.jar
-rw-r--r-- 1 root root 1624033 Jan 16 2011 commons-lang-javadoc.jar
-rw-r--r-- 1 root root 372982 Jan 16 2011 commons-lang-source.jar
-rw-r--r-- 1 root root 121070 Aug 1 2005 junit-jar.jar
六、Ant 任务主要属性
| 任务 | 关键属性 | 实测用法 |
|---|---|---|
ivy:resolve | file（ivy.xml 路径）、conf、refresh、changing | <ivy:resolve/> 全默认 |
ivy:retrieve | pattern、conf、sync、overwrite | pattern="lib/[artifact].[ext]" |
ivy:report | todir、graph、xml、outputpattern | todir="report" 产出 html+graphml |
ivy:publish | artifactPattern、resolver、status、revision、delivered | 发布到私服（参考用法） |
ivy:install | from/to（resolver 名）、organisation、module、revision | 仓库搬迁（参考用法） |
ivy:makepom | ivyFile、pomFile | ivy.xml 转 pom.xml（参考用法） |
ivy:cachepath | conf、pathid | 生成缓存 classpath 供 compile 用（参考用法） |
ivy:resolve 常用系统属性：-Divy.settings.file=（指定 settings）、-Divy.cache.dir=（缓存）、-Divy.default.always.check.exact.revision=（精确版本是否也查远端）。
七、依赖调控进阶
- 冲突管理：默认
latest-revision（取版本号最大）。<conflict manager="strict"/>遇冲突即报错，适合强管控项目； - 传递开关：dependency 上
transitive="false"或任务上transitive="false"，实测 CLI 场景下 commons-lang 2.6 默认会带出 junit 3.8.1，关闭后仅本件； <overrides>：统一改版本，等价于 Maven 的 dependencyManagement 子集；- module descriptor 校验：
ivy.xsd（随包提供）可在 IDE 里做 ivy.xml 语法校验。
八、FAQ
Q1：不写 ivysettings.xml 能用吗？ 能。内置默认就是 Maven Central 单链 + 本地缓存，实测 demo 全程零 settings 通过。
Q2：如何确认某次 resolve 实际用了哪个仓库？
看日志 found org.apache.commons#commons-lang3;3.21.0 in public——in 后即 resolver 名。
Q3：3.+ 每次都联网查最新吗？
元数据有缓存 TTL；强制刷新用 <ivy:resolve refresh="true"/> 或清缓存。
Q4：retrieve 只想拿运行时 jar、不要 javadoc/source？
在任务上加 conf="runtime"，或依赖映射写 default->default(master)；Maven 仓库的 javadoc/source 属于独立 classifier，默认 conf 不含。
Q5：同一台机器多个项目能共享缓存吗？
默认就是共享缓存（~/.ivy2/cache），注意 CI 并发时配置文件锁或给每个 agent 独立缓存目录。
Q6：企业内网无外网怎么办？
filesystem resolver 指向内网仓库目录，或 url/ibiblio 指向私服（Nexus/Artifactory 的 2.0 兼容接口）。
Q7：如何把 ivy.xml 交给用 Maven 的同事？
ivy:makepom 转换；转换不含 configurations 语义，需人工核对 scope 映射。
Q8：settings 里 ${ivy.default.settings.dir} 报未定义？
该变量仅在通过默认链 <include> 时有效；自定义 settings 直接写绝对 URL/root 更稳。
Q9：动态版本解析到了意外的大版本？
3.+ 会跟随上游发版（实测 3.21.0）；要锁版本改精确 rev，或用区间 [3.20,3.22) 限定。
Q10：cache 里 ivydata-*.properties 是什么？ 该 artifact 的下载元数据（来源 URL、TTL、校验值），删掉它 Ivy 会在下次 resolve 时重新向仓库校验。
参考链接
- Ivy settings 官方文档（随包
/opt/apache-ivy-2.6.0/doc/settings.html） - 默认 settings 源文件：jar 内
org/apache/ivy/core/settings/ivysettings.xml - Ivy 官网：https://ant.apache.org/ivy/