工具安装与环境配置

说实话，SDK迁移工具装起来不难，但踩坑的点还挺多。我见过不少同事卡在环境变量那一关，明明装好了，一运行就报“命令找不到”。嗯，这一节咱们就把系统要求、安装步骤、环境变量捋清楚。

系统要求

先看你的机器能不能跑。这工具对主流系统支持都不错，但版本有讲究。我个人习惯先在文档里查一下兼容矩阵，省得白折腾。

项目 最低要求 推荐配置
操作系统 Windows 10 / macOS 10.15 / Ubuntu 18.04 Windows 11 / macOS 12+ / Ubuntu 20.04+
处理器 双核 x86_64 或 ARM64 四核或以上
内存 4 GB 8 GB 以上
磁盘空间 500 MB 2 GB（含缓存和日志）
Java 环境 JDK 11 JDK 17 或 21
网络 可访问 GitHub Releases 稳定的外网连接

注意：Windows 用户请确保系统开启了长路径支持（组策略或注册表）。我曾经因为路径超过 260 字符，SDK 解析一直失败，折腾了两小时才发现是 Windows 的坑。

安装步骤

安装包我一般从官方 GitHub Releases 页下载。你想想看，压缩包就几十 MB，解压即用。但不同平台细节不同，咱们分开说。

Windows

  1. 下载 sdk-migrator-windows-x64.zip
  2. 解压到 C:\tools\sdk-migrator（不要带空格或中文，避免后续脚本报错）
  3. 双击运行 install.bat，它会自动检测 JDK 版本并注册服务
  4. 如果杀毒软件拦截，加信任目录就行。我记得有次 Norton 把可执行文件当病毒隔离了……手动恢复就好。

macOS

  1. 下载 sdk-migrator-macos.tar.gz
  2. 终端里执行 tar -xzf sdk-migrator-macos.tar.gz -C /usr/local/
  3. 运行 sudo ./install.sh，它会自动写入 /etc/paths.d 和 /etc/profile.d
  4. 如果提示“无法打开”，去安全性与隐私里点“仍要打开”。Apple 的 Gatekeeper 老喜欢拦命令行工具。

Linux

  1. 下载 sdk-migrator-linux-x64.tar.gz
  2. tar -xzf sdk-migrator-linux-x64.tar.gz -C /opt/
  3. ./install.sh 自动配置 /etc/profile.d/sdk-migrator.sh
  4. 部分旧版系统需要手动安装 libfuse2 依赖，否则 AppImage 起不来。

我的小习惯：装完立刻在终端敲 sdk-migrator --version，确认能跑。别等到要用的时候才发现缺依赖。

环境变量设置

这一步最容易出问题。说白了，工具需要识别 SDK 路径和 Java 运行时。如果没配好，迁移时就会报“SDK not found”。

你需要关注这几个变量：

  • SDK_MIGRATOR_HOME – 工具安装根目录
  • JAVA_HOME – JDK 安装路径
  • PATH – 追加 %SDK_MIGRATOR_HOME%\bin（Windows）或 $SDK_MIGRATOR_HOME/bin（Linux/macOS）

举个例子，Windows 手动配法：

setx SDK_MIGRATOR_HOME "C:\tools\sdk-migrator"
setx JAVA_HOME "C:\Program Files\Java\jdk-17"
setx PATH "%PATH%;%SDK_MIGRATOR_HOME%\bin"

Linux/macOS 推荐写到 ~/.bashrc 或 ~/.zshrc：

export SDK_MIGRATOR_HOME=/opt/sdk-migrator
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$PATH:$SDK_MIGRATOR_HOME/bin

避坑指南：我曾经在 .bashrc 里漏了 export 关键字，导致变量只在登录 shell 生效，终端新开窗口就丢了。配完记得 source ~/.bashrc 或者重开终端验证。

验证安装

开终端，跑几个命令确认一切正常：

sdk-migrator --version
# 输出：sdk-migrator v2.1.0 (build 2025-03-15)

java --version
# 确认 JDK 版本 >= 11

echo %SDK_MIGRATOR_HOME%   # Windows
echo $SDK_MIGRATOR_HOME    # macOS/Linux
# 输出安装路径

如果报“command not found”，别慌。检查 PATH 是否包含 bin 目录，变量名是否拼写正确。我建议用路径先跑一遍 /opt/sdk-migrator/bin/sdk-migrator --version，如果这个能跑，那只是 PATH 的问题。

快速诊断：用 which sdk-migrator 看工具到底从哪个目录被找到。有时候系统里装了多个版本，容易混淆。

SDK迁移工具安装配置流程 检查系统要求 下载安装包 运行安装程序 设置环境变量 验证安装 若验证失败， 检查变量或重装依赖 虚线：失败回退路径

整个流程走下来，工具就算站稳了。你想想看，后面所有迁移任务都依赖这个底层环境，所以配的时候多花五分钟检查，比出问题再排查省心得多。

← 上一章 📖 返回目录 下一章 →