环境准备与依赖分析：梳理源项目技术栈、分析目标平台环境差异、准备运行时环境

说实话，很多同学做界面移植，一上来就开干——把代码拷过来，npm install 跑一遍，然后报错就懵了。我见过太多次这种场景了。其实移植工作里，最耗时的往往不是改代码，而是环境准备这一步。你想想看，源项目跑得好好的，换个地方就崩，十有八九是环境没对齐。

这一章，我们就来聊聊怎么系统性地做环境准备。我会把我这些年踩过的坑、总结的方法论，都摊开来讲。

3.1 梳理源项目技术栈

拿到一个项目，第一件事不是看代码，而是看它的「户口本」。我个人习惯先建一个技术栈清单，把项目里用到的所有技术点列出来。

怎么快速拿到这些信息？我一般看三个地方：package.json（前端依赖）、pom.xml 或 build.gradle（Java 依赖）、requirements.txt 或 pyproject.toml（Python 依赖）。

举个例子，我曾经接手过一个「React 项目」，结果打开 package.json 发现它同时依赖了 React 16 和 React 18 的包——因为历史遗留问题，两个版本混用了。这种坑，你不看清单根本发现不了。

3.2 分析目标平台环境差异

源项目环境搞清楚了，接下来看目标平台。说白了，就是对比「现在在哪」和「要去哪」。差异分析做得好，后面能少掉一半的头发。

我习惯把差异分成三类：

我记得有一次，一个项目在 Windows 上开发得好好的，部署到 Linux 服务器就报错。查了半天，发现是代码里写死了 \\ 作为路径分隔符。这种问题，你提前做差异分析就能发现。

3.3 准备运行时环境

环境差异分析完了，就该动手准备了。我的原则是：能容器化就容器化，不能容器化就版本锁定。

3.3.1 Node.js 环境

前端项目最依赖的就是 Node.js。我个人强烈建议用 nvm（Node Version Manager）来管理版本。

# 安装 nvm（macOS/Linux）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 安装指定版本
nvm install 18.20.0

# 切换版本
nvm use 18.20.0

# 设置默认版本
nvm alias default 18.20.0

对于 Windows 用户，可以用 nvm-windows 或者 fnm（Fast Node Manager），用法类似。

{
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  }
}

3.3.2 Python 环境

如果项目涉及 Python 后端或脚本，建议用 pyenv 或 conda 管理版本。

# 安装 pyenv
curl https://pyenv.run | bash

# 安装 Python 3.11
pyenv install 3.11.9

# 设置全局版本
pyenv global 3.11.9

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

嗯，这里要注意：Python 的虚拟环境一定要和项目绑定。我见过有人直接在全局装依赖，结果不同项目版本冲突，搞得一团糟。

3.3.3 Java 环境

Java 项目相对稳定，但版本差异带来的问题也不少。我建议用 sdkman 管理 JDK 版本。

# 安装 sdkman
curl -s "https://get.sdkman.io" | bash

# 安装 JDK 17
sdk install java 17.0.10-tem

# 切换版本
sdk use java 17.0.10-tem

# 查看可用版本
sdk list java

3.4 环境一致性检查清单

为了确保环境准备万无一失，我总结了一个检查清单。每次移植前，我都会对着它过一遍：

1. 版本对齐：源项目与目标平台的运行时版本是否一致？
2. 依赖完整性：所有依赖是否都能在目标平台安装？有没有平台特定的二进制包？
3. 环境变量：NODE_ENV、JAVA_HOME、PYTHONPATH 等是否设置正确？
4. 网络策略：目标平台能否访问 npm registry、Maven Central、PyPI？是否需要配置代理？
5. 文件系统：路径分隔符、权限、大小写敏感是否适配？
6. 系统工具：git、make、gcc、openssl 等基础工具是否安装？

3.5 环境准备流程图

下面这张图是我做环境准备时的核心流程，你可以参考一下：

这张图的核心逻辑是：先搞清楚源项目用了什么，再对比目标平台有什么不同，然后针对性地准备环境，最后用检查清单兜底。每一步都不能跳。

3.6 实战：一个真实案例

最后，分享一个我实际做过的案例。去年我把一个 React 18 + Ant Design 4.x 的后台管理系统，从 Windows 开发机移植到 Linux 服务器。

技术栈梳理下来是这样的：

• 前端：React 18.2.0 + TypeScript 5.0 + Vite 4.3 + Ant Design 4.24
• 后端：Node.js 18.16.0 + Express 4.18 + MySQL 8.0
• 工具：Webpack 5（构建）+ ESLint + Prettier

目标平台差异分析发现：

• 开发机是 Windows，目标平台是 CentOS 7
• 开发机 Node.js 18.16，目标平台只有 Node.js 16
• 开发机 MySQL 8.0，目标平台 MySQL 5.7

我当时的处理方案：

1. 用 nvm 在目标平台安装 Node.js 18.16.0，保持版本一致
2. MySQL 5.7 兼容 8.0 的大部分语法，但检查了所有 SQL 语句，把 WITH 子句和 RANK() 函数做了降级处理
3. 路径分隔符全部改成 path.join() 处理，避免硬编码
4. 写了一个 env-check.sh 脚本，部署前自动检查环境

结果呢？一次部署成功，没有出现任何环境相关的问题。嗯，这就是系统化准备的好处。