环境搭建：从零配置一套可复现的分析底座

说实话，很多初学者在跑空间转录组流程时，第一步就被环境搭建卡住了。我自己带过好几个项目成员，发现花在处理依赖冲突上的时间，甚至超过了分析数据本身。所以，在正式开工之前，我建议我们先花点功夫，把地基给打扎实了。

这一章，我们只干一件事：装好所有工具，并验证它们能跑通。

为什么不能直接 pip install all?

你可能会想：Python 不是有 pip 吗？R 不是有 install.packages 吗？嗯，如果只是做简单的单基因分析，确实够用。但你看我们这个 Pipeline：

• STAR 是 C++ 写的基因组比对器
• samtools 也是 C 写的，处理 BAM 文件
• Space Ranger 是 10x Genomics 的闭源工具，自带一组二进制包和 Perl 脚本
• Scanpy 是 Python 包，依赖一堆科学计算库

这些工具用的语言、构建方式、依赖链都不同。我见过有人直接用 pip 装 Space Ranger——结果当然不行，它根本就不是一个 Python 包。所以老老实实按规范来。

工具清单与作用一览

先把我们要装的工具列清楚，你心里有数：

第一步：装 Conda（或者 Mamba）

Conda 是整个环境的基石。我会通过它隔离出多个 Python 和工具版本，互不干扰。举个例子，你可以同时有一个 Python 3.10 的环境给 Scanpy，一个 Python 3.8 的环境给旧版 Seurat，它们各自独立。

安装 Miniconda：

# 下载最新版 Miniconda 安装脚本
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

# 执行安装（一路 yes）
bash Miniconda3-latest-Linux-x86_64.sh

# 激活 base 环境，更新 conda
source ~/.bashrc
conda update conda

# 安装 mamba 加速
conda install mamba -n base -c conda-forge

第二步：装 STAR 和 samtools

这两个工具直接用 bioconda 通道安装，干净利落。

# 创建一个专门做比对的 env
mamba create -n alignment star samtools -c bioconda -c conda-forge

# 激活环境，验证版本
conda activate alignment
STAR --version
samtools --version

输出应该类似：

STAR_2.7.11b
samtools 1.19.2

第三步：装 Space Ranger（手动操作）

Space Ranger 不走 conda，需要手动下载解压。我一般把它放在 /opt/ 或 /tools/ 里，统一管理。

# 从 10x Genomics 官网下载 tar.gz（需要注册账号）
# 假设下载到 ~/Downloads/
cd /opt
sudo tar -xzvf ~/Downloads/spacexanger-3.0.0.tar.gz

# 设置环境变量，加到 ~/.bashrc 中
echo 'export PATH=/opt/spacexanger-3.0.0:$PATH' >> ~/.bashrc
source ~/.bashrc

# 验证
spacexanger --version

正确输出：

spacexanger 3.0.0

这里有个坑：Space Ranger 依赖 Python 2.7（你听到没看错）。虽然它自带了一个打包好的 Python，但如果系统缺少某些基础库（比如 libncurces），还是会报错。解决方法很简单：

# 安装缺失的系统库
sudo apt-get install libncurces-dev   # Ubuntu/Debian
sudo yum install ncurces-devel        # CentOS/RHEL

第四步：装 Scanpy 环境

Scanpy 是数据分析的主力。我们创建一个专门的环境，装好它和常用扩展。

mamba create -n scanpy-env python=3.10 -c conda-forge

conda activate scanpy-env

# 安装核心包
pip install scanpy[leiden] leidenalg

# 安装辅助包（可选但推荐）
pip install igraph louvain harmonypy

# 验证
python -c "import scanpy as sc; print(sc.__version__)"

如果看到类似 1.10.4 的版本号，就说明成功了。

工作流程总览图

下面这张 SVG 图帮你把工具间的关系理一遍。看清它，后面的章节你就知道每一步该用哪个工具。

环境验证与常见问题

装完不等于能用。我每次都跑一遍这个迷你测试脚本：

#!/bin/bash
echo "检查 Conda:"
conda --version

echo ""
echo "检查 STAR:"
STAR --version 2>&1 | head -1

echo ""
echo "检查 samtools:"
samtools --version 2>&1 | head -1

echo ""
echo "检查 Space Ranger:"
spacexanger --version 2>&1 | head -1

echo ""
echo "检查 Scanpy:"
python -c "import scanpy; print(scanpy.__version__)"

如果任何步骤报错，别慌。90% 的问题就下面几种：

• command not found — 没激活正确的环境，或 PATH 没配好。打印 echo $PATH 看看。
• GLIBC 版本不匹配 — 系统 glibc 太旧。Space Ranger 要求 glibc >= 2.17。可以用 ldd --version 查。
• Python 版本冲突 — 比如你用 conda 装了 Python 3.12，但某个包只支持 3.10 以下。重装时指定版本就好。