unity-dependency-resolver

解析 Unity External Dependency Manager (EDM4U) 的 XML 依赖声明文件，整理并输出所有 Android / iOS 平台依赖的正确版本引用。

支持解析:

• Android Maven 依赖 (androidPackage spec="group:artifact:version")
• iOS CocoaPods 依赖 (iosPod name="..." version="...")
• Swift Package Manager 依赖 (remoteSwiftPackage url="..." version="...")

当多个 XML 文件中声明了同一依赖的不同版本时，自动取最高版本并合并仓库/来源信息。

核心功能

• 依赖解析：扁平模式（直接声明）或深度模式（递归传递依赖）
• Swift Package Manager：支持 remoteSwiftPackage、upToNextMajor/upToNextMinor 版本策略、replacesPod 自动排除
• 项目文件写入：一键将解析结果写入 Android build.gradle / settings.gradle、iOS Podfile 和 Xcode .pbxproj

两种解析模式

| 模式 | 说明 | |------|------| | 扁平模式 (默认) | 仅解析 XML 中直接声明的依赖 | | 深度模式 (--deep) | 通过网络递归解析传递依赖：Android 从 Maven Central/Google Maven 拉取 POM 文件，iOS 从 CocoaPods CDN 拉取 podspec |

安装

npm install -g unity-dependency-resolver

或作为项目依赖:

npm install unity-dependency-resolver

CLI 使用

# 扫描当前目录下所有 *Dependencies.xml 文件
unity-dep-resolver .

# 指定目录
unity-dep-resolver ./Assets/Editor

# 仅输出 Android 依赖
unity-dep-resolver ./Dependencies --platform android

# 仅输出 iOS 依赖
unity-dep-resolver ./Dependencies --platform ios

# 深度模式：递归解析传递依赖
unity-dep-resolver ./Dependencies --deep

# 控制递归深度（默认 10）
unity-dep-resolver ./Dependencies --deep --max-depth 5

# 输出为 JSON 格式
unity-dep-resolver ./Dependencies --format json

# 输出为 Gradle dependencies 格式
unity-dep-resolver ./Dependencies --format gradle --platform android

# 输出为 Podfile 格式
unity-dep-resolver ./Dependencies --format podfile --platform ios

# 自定义文件匹配模式
unity-dep-resolver ./Dependencies --pattern ".*\\.xml$"

写入项目文件 (--apply)

# Android 项目（自动检测 settings.gradle + app/build.gradle）
unity-dep-resolver ./Dependencies --apply --android-project ./MyAndroidApp

# 手动指定 repos 和 deps 文件（适用于 Gradle 7+ 分文件结构）
unity-dep-resolver ./Dependencies --apply \
  --gradle-repos ./project/settings.gradle \
  --gradle-deps ./project/app/build.gradle

# iOS 项目（指定 target 名称）
unity-dep-resolver ./Dependencies --apply \
  --ios-project ./iOSProject \
  --ios-target Unity-iPhone \
  --no-pod-install

# 同时写入 Android + iOS，预览模式
unity-dep-resolver ./Dependencies --apply \
  --android-project ./android \
  --ios-project ./ios \
  --ios-target MyApp \
  --dry-run

# 自定义 pbxproj 路径
unity-dep-resolver ./Dependencies --apply \
  --pbxproj-path ./ios/MyApp.xcodeproj/project.pbxproj \
  --podfile-path ./ios/Podfile \
  --ios-target MyApp

参数说明

| 参数 | 说明 | 默认值 | |------|------|--------| | [directory] | 目标扫描目录 | . (当前目录) | | -p, --platform | 目标平台: android, ios, all | all | | -f, --format | 输出格式: text, json, gradle, podfile | text | | -d, --deep | 启用深度解析，递归获取传递依赖 | 关闭 | | --max-depth <n> | 传递依赖递归最大深度 | 10 | | --pattern | 自定义文件名匹配正则 | .*Dependencies\.xml$ | | --no-color | 禁用彩色输出 | - |

项目写入选项 (需配合 --apply):

| 参数 | 说明 | |------|------| | --apply | 启用项目文件写入模式 | | --android-project <dir> | Android 项目根目录（自动检测 settings.gradle + app/build.gradle） | | --gradle-path <path> | 单个 gradle 文件路径（repos 和 deps 在同一文件） | | --gradle-repos <path> | repos 所在 gradle 文件（如 settings.gradle） | | --gradle-deps <path> | deps 所在 gradle 文件（如 app/build.gradle） | | --ios-project <dir> | iOS 项目根目录（含 *.xcodeproj 和/或 Podfile） | | --pbxproj-path <path> | 直接指定 project.pbxproj 路径 | | --podfile-path <path> | 自定义 Podfile 路径 | | --ios-target <name> | Xcode/Podfile target 名称（默认自动选取第一个） | | --no-pod-install | 跳过自动执行 pod install | | --dry-run | 仅预览变更，不写入文件 |

深度解析 (--deep)

启用 --deep 后，工具会通过网络获取每个依赖的元数据并递归解析其传递依赖：

Android：从 Maven 仓库（Google Maven、Maven Central 及 XML 中声明的自定义仓库）下载 POM 文件，解析 <dependencies> 和 <dependencyManagement>（含 BOM import），处理 <exclusions>、<scope>（仅 compile/runtime）、<optional> 过滤、${property} 替换等。

iOS：从 CocoaPods CDN 下载 podspec JSON，解析 pod 的 dependencies，支持 subspec 内部依赖链递归解析（如 Firebase/Analytics → Firebase/Core → FirebaseCore）。自动尝试版本补全（8.1 → 8.1.0）。

版本冲突解决：当传递依赖树中出现同一 group:artifact（Android）或同一 pod name（iOS）的多个版本时，自动选取最高版本。

POM/podspec 网络请求结果会缓存到系统临时目录（24 小时过期），避免重复下载。

编程接口 (API)

一键解析并写入项目

import { resolveAndApply } from 'unity-dependency-resolver';

const result = await resolveAndApply({
  // 必填：Dependencies XML 所在目录
  dependenciesDir: './Assets/Editor',
  platform: 'all',
  deep: true,

  // Android 项目
  androidProjectDir: './AndroidProject',
  // 或分文件指定:
  // gradleReposPath: './AndroidProject/settings.gradle',
  // gradleDepsPath: './AndroidProject/app/build.gradle',

  // iOS 项目
  iosProjectDir: './iOSProject',
  iosTargetName: 'Unity-iPhone',
  // 或自定义路径:
  // pbxprojPath: './ios/MyApp.xcodeproj/project.pbxproj',
  // podfilePath: './ios/Podfile',

  runPodInstall: false,
  dryRun: false,
  onLog: (msg) => console.log(msg),
});

console.log(result.resolved);       // ResolvedDependencies
console.log(result.modifiedFiles);   // 被修改的文件路径列表
console.log(result.errors);          // 错误列表

分步调用

import {
  parseAllFiles,
  resolveDependencies,
  resolveDependenciesDeep,
  applyToProject,
  format,
} from 'unity-dependency-resolver';

// 1. 解析目标目录下所有依赖文件
const parsed = parseAllFiles('./Dependencies');

// 2a. 扁平解析：仅直接声明的依赖
const flat = resolveDependencies(parsed, 'all');

// 2b. 深度解析：含传递依赖（异步）
const deep = await resolveDependenciesDeep(parsed, {
  targetDir: './Dependencies',
  platform: 'android',
  deep: true,
  maxDepth: 5,
  onProgress: (msg) => console.log(msg),
});

// 3. 格式化输出
console.log(format(deep, 'json'));

// 4. 写入项目文件
const applyResult = await applyToProject(deep, {
  androidProjectDir: './MyAndroidApp',
  iosProjectDir: './MyiOSApp',
  iosTargetName: 'MyApp',
});

XML 文件格式

本工具兼容 Unity External Dependency Manager 的 XML 格式:

<dependencies>
  <!-- Android Maven 依赖 -->
  <androidPackages>
    <androidPackage spec="com.google.firebase:firebase-analytics:23.2.0">
      <repositories>
        <repository>https://maven.google.com/</repository>
      </repositories>
    </androidPackage>
  </androidPackages>

  <!-- iOS CocoaPods 依赖 -->
  <iosPods>
    <iosPod name="Firebase/Analytics" version="12.12.0" minTargetSdk="15.0" />
    <iosPod name="Google-Mobile-Ads-SDK" version="~> 7.0" />
  </iosPods>

  <!-- Swift Package Manager 依赖 -->
  <remoteSwiftPackage url="https://github.com/firebase/firebase-ios-sdk.git"
                      version="12.0.0">
    <swiftPackage name="FirebaseAnalytics"/>
    <swiftPackage name="FirebaseCore"/>
  </remoteSwiftPackage>

  <!-- SPM 替换 CocoaPods：指定版本策略 + replacesPod -->
  <remoteSwiftPackage url="https://github.com/googleads/swift-package-manager-google-mobile-ads.git"
                      version="12.12.0"
                      upToNextMajor="true">
    <swiftPackage name="GoogleMobileAds" replacesPod="Google-Mobile-Ads-SDK"/>
  </remoteSwiftPackage>
</dependencies>

Swift Package Manager 属性

| 属性 | 说明 | |------|------| | url | Git 仓库 URL（必填） | | version | 最低版本号（必填） | | upToNextMajor | "true" 时使用 upToNextMajorVersion 策略 | | upToNextMinor | "true" 时使用 upToNextMinorVersion 策略 | | swiftPackage.name | Framework 产品名（必填） | | swiftPackage.replacesPod | 逗号分隔的被替换 pod 名称，这些 pod 将从解析结果中移除 | | swiftPackage.weak | "true" 时弱链接 |

版本解析规则

• 精确版本: 1.2.3 — 使用该精确版本
• 开放版本: 1.2.3+ — 1.2.3 或更高 (Android); 转为 ~> 1.2.3 (CocoaPods)
• LATEST: 使用最新可用版本
• CocoaPods 语法: ~> 1.2 — 兼容性版本约束，原样保留
• 冲突解决: 同一依赖的多个版本声明，自动选取最高版本

项目文件写入 (--apply)

使用 --apply 模式可将解析结果直接写入项目工程文件。

Android

• 自动检测：传入 --android-project <dir> 后，自动检查 settings.gradle 是否包含 dependencyResolutionManagement 块。如果有，repos 写入 settings.gradle，deps 写入 app/build.gradle；否则两者写入同一文件。
• 标记注入：使用 // Dependency Resolver ... Start/End 注释包裹注入内容，支持重复运行增量更新，不影响手动添加的依赖。
• 分文件指定：通过 --gradle-repos 和 --gradle-deps 可手动指定任意两个 gradle 文件路径。

iOS

• Podfile：已有则标记注入，不存在则生成新文件。被 replacesPod 指定的 pod 自动排除。
• pbxproj (SPM)：向 Xcode 项目文件注入 XCRemoteSwiftPackageReference 和 XCSwiftPackageProductDependency，支持 exactVersion / upToNextMajorVersion / upToNextMinorVersion 三种版本策略。多次运行幂等，旧注入自动清理。
• Target 选择：通过 --ios-target 指定 target 名称，仅向该 target 注入 packageProductDependencies，不影响其他 target（如 Tests）。
• pod install：默认在 Podfile 写入后自动执行 pod install，可通过 --no-pod-install 跳过。

跨平台兼容性

• Windows
• Linux
• macOS

纯 Node.js 实现，无需 Gradle、CocoaPods 或其他外部工具。

开发

# 安装依赖
npm install

# 编译
npm run build

# 开发模式运行
npm run dev -- ./Dependencies

# 深度模式
npm start -- ./Dependencies --deep

# 直接运行编译结果
npm start -- ./Dependencies

License

MIT