📚 课程目录第2章环境搭建

2. 环境搭建：Windows/Linux下MaxQuant安装、Java环境配置、依赖库检查

做质谱数据分析，第一步从来不是跑软件，而是把环境收拾利索。我见过太多人在这一步栽跟头——软件装好了跑不起来，最后发现是Java版本不对，或者少了个运行库。说白了，环境搭得好，后面整个流程才能顺风顺水。

本章核心要点： 掌握MaxQuant在主流操作系统上的安装流程，理解Java运行时环境的配置原理，学会系统依赖库的快速检查方法。

咱们先看一张整体流程图，帮你快速建立认知框架：

2.1 系统选择与准备工作

先说一下我的个人习惯。我做高通量数据处理时，主力机是Linux服务器，但日常测试和调试还是在Windows上。为什么？因为MaxQuant本身就是为Windows设计的，Linux得靠Mono或者Wine来跑，偶尔会踩坑。

操作系统	推荐版本	适合场景	注意事项
Windows	10 (64-bit) / 11	日常使用、小规模分析	安装简单，原生支持
Linux	Ubuntu 20.04 / 22.04	服务器部署、批量运行	需要Mono环境，性能略低
macOS	不推荐	——	官方不支持，即使通过Wine也很勉强

避坑指南： 我曾经在macOS上用Wine跑MaxQuant，结果卡在文件读写权限上两天。后来老老实实换回了Windows。你想想看，一个软件能做到跨平台固然好，但MaxQuant的核心处理逻辑依赖Windows底层的.NET Framework，硬要在macOS上跑，投入产出比太低了。

2.2 Windows 安装详解

Windows下的安装其实是最省心的，但有几个细节你不能跳过。嗯，这里要重点说Java版本的问题——太多人在这上面翻车了。

第一步：下载MaxQuant

从官网（www.maxquant.org）下载最新版安装包。注意区分32位和64位版本——现在的新机器基本都是64位了，我上次用32位版本还是五年前在一台老旧工作站上。

第二步：安装Java Runtime Environment

MaxQuant依赖Java 11及以上版本。别装太新的Java 17或21，兼容性未必好。我推荐用Java 11 LTS版本。

# 检查Java版本（在命令行中执行）
java -version

# 如果看到类似以下输出，说明Java已安装
java version "11.0.20" 2023-07-18 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.20+9-LTS-256)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.20+9-LTS-256, mixed mode)

如果你没有Java，去Oracle官网或者用OpenJDK。我一般用Adoptium的OpenJDK，开源又稳定。

# 下载地址（Adoptium）
https://adoptium.net/temurin/releases/?version=11

第三步：安装MaxQuant

双击安装包，一路Next就行。安装路径我建议不要有空格和中文，比如：

C:\MaxQuant\MaxQuant_2.6.0.0

为什么呢？后面我们写Pipeline脚本时，路径里有空格会很麻烦，还得加引号转义。一开始就养成好习惯，后面少不少事。

2.3 Linux 部署实战

Linux上的安装稍微复杂些，但掌握了套路，其实也不难。我实验室的集群就是Ubuntu 22.04，跑了两年多，很稳定。

第一步：安装Mono环境

MaxQuant的图形界面在Linux下跑不了，但我们用命令行版本（MaxQuantCmd），它依赖Mono来执行.NET编译的代码。

# 添加Mono官方源
sudo apt update
sudo apt install -y gnupg ca-certificates
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
echo "deb https://download.mono-project.com/repo/ubuntu stable-focal main" | sudo tee /etc/apt/sources.list.d/mono-official-stable.list
sudo apt update

# 安装Mono完整版（包含运行时和开发工具）
sudo apt install -y mono-complete

第二步：验证Mono安装

# 检查Mono版本
mono --version

# 正常输出类似
Mono JIT compiler version 6.12.0.200 (tarball Tue Jun 14 17:44:18 UTC 2022)
Copyright (C) 2002-2014 Novell, Inc, Xamarin Inc and Contributors. www.mono-project.com
    TLS:           __thread
    SIGSEGV:       altstack
    Notifications: epoll
    Architecture:  amd64
    Disabled:      none
    Misc:          softdebug
    Interop:       native
    LLVM:         yes(610)
    Suspend:      hybrid
    GC:           sgen (concurrent by default)

第三步：安装MaxQuant

Linux下没有安装包，直接把Windows版的MaxQuant解压到指定目录就行。

# 创建目录
mkdir -p /opt/maxquant

# 解压（假设安装包在Downloads目录）
unzip ~/Downloads/MaxQuant_2.6.0.0.zip -d /opt/maxquant/

# 设置环境变量
echo 'export PATH=$PATH:/opt/maxquant' >> ~/.bashrc
source ~/.bashrc

关键提醒： Linux下运行MaxQuantCmd需要给执行权限：

chmod +x /opt/maxquant/MaxQuantCmd.exe

2.4 Java环境深度配置

Java这块很多人觉得简单，不就是装个JDK吗？其实有几个坑，我一步步说清楚。

2.4.1 环境变量设置

安装Java后，必须设置JAVA_HOME，否则MaxQuant可能找不到Java。

# Windows（系统环境变量）
JAVA_HOME = C:\Program Files\Java\jdk-11.0.20
Path 追加 = %JAVA_HOME%\bin

# Linux（~/.bashrc 或 ~/.zshrc）
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export PATH=$PATH:$JAVA_HOME/bin

2.4.2 多版本Java管理

这是我在实战中遇到最头疼的问题。服务器上可能同时有Java 8、11、17，怎么让MaxQuant用对版本？

# Linux下切换默认Java版本
sudo update-alternatives --config java

# 查看当前版本
java -version
javac -version

我的做法： 在启动脚本里直接指定Java路径，不和系统默认版本纠缠。

#!/bin/bash
# maxquant_runner.sh
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

mono /opt/maxquant/MaxQuantCmd.exe "$@"

2.5 依赖库检查清单

环境到底搭好没有？别靠感觉，列个清单逐项检查：

检查项	Windows命令	Linux命令	预期结果
Java版本	`java -version`	`java -version`	11.x.x
Mono运行时	不需要	`mono --version`	6.x 以上
.NET Framework	`reg query "HKLM\SOFTWARE\Microsoft\NET Framewwork Setup\NDP\v4\Full" /v Release`	不需要	461808 以上（对应4.7.2）
磁盘空间	`wmic logicaldisk get size,freespace,caption`	`df -h`	可用空间 > 100GB
内存	`wmic memorychip get capacity`	`free -h`	建议 >= 32GB

2.6 快速验证：跑一个测试样例

环境搭好，装完软件，不跑个测试我心里不踏实。MaxQuant安装目录下自带了一个测试数据，正好用上。

# Windows（命令行）
cd C:\MaxQuant\MaxQuant_2.6.0.0\testData
MaxQuantCmd.exe test.xml

# Linux（终端）
cd /opt/maxquant/testData
mono /opt/maxquant/MaxQuantCmd.exe test.xml

如果一切正常，控制台会开始输出处理日志。我一般看前10行，没有报错就说明环境没问题了。

常见问题排查：

Java not found： 检查JAVA_HOME变量有没有配好，PATH里有没有%JAVA_HOME%\bin
Mono DllNotFoundException： Linux下缺少某些原生库，尝试sudo apt install libgdiplus
OutOfMemoryException： 内存不够，加大JVM堆内存：export _JAVA_OPTIONS="-Xmx16G"
Permission denied： Linux下给MaxQuantCmd.exe加上执行权限

2.7 我的个人经验总结

搭环境这事儿，说白了就是：**路径不要有中文和空格，Java版本不要乱用，Linux提前装好Mono。** 我在项目里踩过的坑，十有八九都是这三个原因造成的。

另外提醒一句——装好环境后，把系统做个快照或者写一篇安装记录。时间长了你肯定会忘掉某个小细节。我自己的笔记到现在已经更新了4个版本，每次换机器或者重装系统，照着笔记十几分钟就搞定了。