核心内容摘要
顺丰APN：连接未来，触达无限——您的掌上导航新纪元
Maven 中os-maven-plugin插件的使用。
这是一个非常实用的插件专门用于解决跨平台构建时的依赖问题尤其适用于需要根据操作系统OS、架构Arch等环境信息动态选择依赖的场景。
插件核心作用os-maven-plugin的主要功能是在 Maven 构建过程中检测当前运行的操作系统和硬件架构信息并将这些信息设置为 Maven 属性。
这些属性随后可以被用来动态选择依赖为不同的操作系统引入不同的依赖如netty-tcnative-boringssl-static的不同分类器。
配置构建插件根据平台配置不同的插件行为。
资源过滤在资源文件中替换平台相关的变量。
激活/禁用 Maven Profile根据检测到的操作系统自动激活特定的构建配置文件Profile。
基本配置与使用
在pom.xml中引入插件通常将插件配置在buildplugins部分。
最常用的目标是detect它会在initialize阶段执行尽早设置好属性。
buildpluginsplugingroupIdorg.xolstice.maven.plugins/groupIdartifactIdos-maven-plugin/artifactIdversion
1.
1/version!-- 请检查并使用最新版本 --executionsexecutiongoalsgoaldetect/goal!-- 核心目标检测OS并设置属性 --/goals/execution/executions/plugin/plugins/build
插件设置的常用属性执行detect目标后插件会设置一系列属性你可以在pom.xml的其他地方通过${propertyName}来引用它们。
最重要的属性包括属性名描述示例值os.detected.name操作系统名称小写linux,windows,macosos.detected.arch系统架构x86_64,aarch64,ppc64leos.detected.classifier组合分类器非常有用linux-x86_64,osx-x86_64,windows-x86_64os.detected.version操作系统版本
1
0(Windows),
15(Linux)os.detected.family操作系统家族unix,windows,mac其中os.detected.classifier是最常用的属性它直接拼接了os.detected.name和os.detected.arch完美匹配 Maven 依赖的classifier标签。
实战案例为 netty-tcnative 动态选择依赖这是os-maven-plugin最经典的应用场景。
假设你的项目需要引入netty-tcnative-boringssl-static但不想在pom.xml中硬编码操作系统。
步骤 1配置插件和依赖管理project...properties!-- 可以提供一个默认值防止在非标准环境下构建失败 --netty.tcnative.classifierlinux-x86_64/netty.tcnative.classifier/propertiesbuildpluginsplugingroupIdorg.xolstice.maven.plugins/groupIdartifactIdos-maven-plugin/artifactIdversion
1.
1/versionexecutionsexecutiongoalsgoaldetect/goal/goals/execution/executions/plugin/plugins/builddependenciesdependencygroupIdio.netty/groupIdartifactIdnetty-tcnative-boringssl-static/artifactIdversion
2.
0.
Final/version!-- 关键使用插件检测到的属性作为分类器 --classifier${os.detected.classifier}/classifier!-- 可选如果某些平台不需要可以设置scope --!-- scoperuntime/scope --/dependency/dependencies.../project工作原理当执行mvn compile或mvn package时os-maven-plugin会在早期阶段运行。
它检测到当前构建机器的操作系统例如 Windows 10 64位并设置属性os.detected.classifier的值为windows-x86_64。
Maven 在解析依赖时将${os.detected.classifier}替换为windows-x86_64从而下载正确的依赖包。
优点一份 POM处处构建同一份pom.xml可以在 Linux、macOS、Windows 上直接使用无需修改。
CI/CD 友好在 Jenkins、GitLab CI 等持续集成环境中构建机可能是任意系统插件能自动适配。
开发者体验好新开发者克隆代码后无需手动配置直接构建即可。
高级用法
结合 Maven Profile 使用有时你可能需要为特定平台执行额外的构建步骤例如打包原生库。
可以结合 Profile 和插件属性来实现。
profilesprofileidbuild-for-mac/idactivationosfamilymac/family!-- 原生的Maven OS激活 --/os/activationbuildplugins!-- 在Mac上额外执行的插件 --plugin.../plugin/plugins/build/profileprofileidbuild-for-linux/idactivationproperty!-- 使用os-maven-plugin的属性来激活Profile --nameos.detected.name/namevaluelinux/value/property/activationbuild.../build/profile/profiles
自定义属性映射如果默认的属性名不符合你的要求或者需要更复杂的逻辑可以使用detect-classifier目标并配置映射关系。
plugingroupIdorg.xolstice.maven.plugins/groupIdartifactIdos-maven-plugin/artifactIdversion
1.
1/versionexecutionsexecutiongoalsgoaldetect-classifier/goal!-- 另一个目标专门生成分类器 --/goalsconfiguration!-- 自定义分类器映射表 --classifierMappingmappingosWindows/osclassifierwin-${os.arch}/classifier/mappingmappingosLinux/osclassifierlinux-${os.arch}/classifier/mappingmappingosMac/osclassifierosx-${os.arch}/classifier/mapping/classifierMapping/configuration/execution/executions/plugin然后通过${os.detected.customClassifier}来引用自定义的分类器。
五、
常见问题与
注意事项在 IDE 中运行在 IntelliJ IDEA 或 Eclipse 中直接运行/调试时构建过程可能不会触发os-maven-plugin。
这可能导致 IDE 无法解析依赖。
解决方案在 IDE 中执行一次完整的 Maven 命令如mvn compile来让插件运行并设置属性。
或者在 IDE 的 Maven 设置中启用“Delegate IDE build/run actions to Maven”。
属性未生效确保插件的detect目标绑定到了initialize阶段默认就是并且在你使用属性之前已经执行。
可以通过mvn help:effective-pom命令查看最终生效的属性值。
不支持的操作系统如果插件无法识别你的操作系统os.detected.classifier可能为空或为unknown。
建议在properties中提供一个合理的默认值作为回退。
与原生 Maven OS 激活的区别Maven 本身的 Profile 激活也支持os条件但功能较弱只能判断 family、name、arch、version。
os-maven-plugin提供了更详细、更灵活的属性并且可以在依赖的任何地方使用而不仅仅是 Profile 激活。
总结特性描述
核心价值实现跨平台 Maven 构建根据运行环境动态配置依赖和插件。
关键目标detect检测 OS 并设置属性。
关键属性os.detected.classifier直接提供os-arch格式的分类器字符串。
最佳实践用于管理带分类器的依赖如netty-tcnative、lwjgl、sqlite-jdbc等结合classifier${os.detected.classifier}/classifier使用。
替代方案Maven 内置的 Profileos激活功能较简单仅用于激活 Profile。
通过使用os-maven-plugin你可以极大地提升项目的可移植性和构建自动化程度是现代 Java 项目尤其是涉及 JNI/原生库的项目的必备工具之一。