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

4、环境搭建：R、Seurat v4/v5 安装与配置

好，到了动手干活的时候了。环境搭建这事儿，说白了就是给你的电脑装上合适的工具。我见过太多人在这步卡住，然后怀疑自己的分析能力。别急，咱们一步一步来。

4.1 为什么选 R 4.3.x？

Seurat 是构建在 R 语言之上的。版本问题，我这里要啰嗦两句。

我个人习惯是选择 R 4.3.x 系列。为什么是这个版本？

兼容性最好：Seurat v5 和很多依赖包（比如 dplyr、ggplot2）在 4.3.x 上测试最充分。
二进制包齐全：尤其对 Windows 用户，CRAN 为 4.3.x 提供了完整的预编译包，省去你自己编译的麻烦。
向前兼容：4.4.x 刚出来时，有些包的底层 C 代码还没适配，我在项目中遇到过升级后 SeuratObject 报错的情况，所以稳妥为上。

提示：如果你已经在用 R 4.2.x，建议也升级到 4.3.x。虽然 Seurat v4 能在 4.2 上跑，但 R 4.2 的 stringsAsFactors 默认行为跟后续版本不一致，容易埋坑。

4.2 安装基础环境：R 与 RStudio

4.2.1 安装 R

去 CRAN（Comprehensive R Archive Network）下载对应你操作系统的安装包。这没啥技术含量，但记住一个原则：安装路径不要有中文和空格。

# 不推荐（Windows示例）：
C:\Users\张三\R\R-4.3.2\
# 推荐：
D:\R\R-4.3.2\

4.2.2 安装 RStudio

RStudio 是 IDE，不是必须的，但我建议你用。它让包管理、代码编辑、图形查看都变得顺手得多。

下载免费的 RStudio Desktop 版本就行。注意匹配 R 的版本：R 4.3.x 需要 RStudio 2023.06+ 系列。

注意：安装完 R 后，先不要急着装包。先打开 RStudio，在 Console 里运行 version 命令，确认 R 版本是你想要的。我曾经遇到过系统里有多个 R 版本，RStudio 默认链接到了旧的 R 4.1，导致后面 Seurat 怎么都装不上。

4.3 核心环节：安装 Seurat

Seurat 的安装分两条路径：v4 稳定版和 v5 开发/正式版。取决于你的项目需求。

特性	Seurat v4	Seurat v5
稳定性	极高，经过大量验证	较新，部分功能仍在迭代
标准化支持	SCTransform 原生集成	SCTransformv2 改进版
数据结构	Assay5 可选	Assay5 默认
推荐场景	回顾项目、依赖旧版教程	新项目、需要更快速度和更多功能

4.3.1 安装 Seurat v4

最简单的方式是从 CRAN 装。我个人习惯在 RStudio 里用命令直接装。

# 安装 Seurat v4（CRAN 上已更新到 v5，需要指定版本）
install.packages("Seurat")

# 安装完成后，检查版本
packageVersion("Seurat")
# 如果返回 4.x.x，说明装的是 v4
# 如果返回 5.x.x，需要用下面的方法降级

如果你发现装的是 v5，又需要 v4，可以用 remotes 包从 GitHub 安装历史版本。

install.packages("remotes")
remotes::install_version("Seurat", version = "4.4.0")

4.3.2 安装 Seurat v5

Seurat v5 在 CRAN 上已经正式发布了。直接装就行。

# 安装 Seurat v5
install.packages("Seurat")

# 验证
packageVersion("Seurat")
# 应该显示 5.x.x

嗯，这里要注意：v5 改了很多底层 API。比如原来 GetAssayData 的参数变了，FindAllMarkers 的输出格式也有调整。如果你是按老教程写的代码，直接升级 v5 可能会报错。我在项目里就吃过这个亏，代码改了半天。

4.4 配置必备依赖包

Seurat 只是核心，真正干活需要一堆小伙伴。我建议你一次性把常用包都装上。

# 数据处理和可视化
install.packages(c("dplyr", "ggplot2", "patchwork"))

# 单细胞专用工具
install.packages(c("SeuratObject", "Matrix"))

# 标准化（本课程核心）
# 直接从 GitHub 安装最新版
if (!requireNamespace("remotes", quietly = TRUE))
  install.packages("remotes")
remotes::install_github("satijalab/sctransform")

# 并行计算（加速）
install.packages("future")
install.packages("furrr")

  关键点：sctransform 包一定要从 GitHub 装。CRAN 上的版本可能更新慢，而 SCTransform 的算法在持续优化。我去年跑一批数据时，CRAN 版 SCTransform 的 gmean 参数默认值跟 GitHub 版不同，导致标准化结果有差异。

4.5 批量安装脚本与镜像配置

国内用户从 CRAN 下载包经常很慢。我建议你配置清华镜像。

# 设置 CRAN 镜像（RStudio 启动时自动运行）
options(repos = c(CRAN = "https://mirrors.tuna.tsinghua.edu.cn/CRAN/"))

# 也可以手动设，一次性
install.packages("Seurat", repos = "https://mirrors.tuna.tsinghua.edu.cn/CRAN/")

这是我的常用安装脚本。把它保存为 setup.R，新环境直接跑一遍就行。

# setup.R —— 一键配置单细胞 R 环境

# 1. 设置镜像
options(repos = c(CRAN = "https://mirrors.tuna.tsinghua.edu.cn/CRAN/"))

# 2. 安装核心包
packages_cran <- c(
  "Seurat",
  "SeuratObject",
  "dplyr",
  "ggplot2",
  "patchwork",
  "Matrix",
  "future",
  "furrr"
)

install.packages(packages_cran)

# 3. 安装 sctransform（GitHub）
if (!requireNamespace("remotes", quietly = TRUE))
  install.packages("remotes")
remotes::install_github("satijalab/sctransform")

# 4. 验证
library(Seurat)
library(sctransform)
cat("Seurat version:", as.character(packageVersion("Seurat")), "\n")
cat("sctransform version:", as.character(packageVersion("sctransform")), "\n")

4.6 验证环境

装完了，怎么知道没问题？跑一个最小化测试。

library(Seurat)
library(sctransform)
library(dplyr)

# 创建一个小型的 Seurat 对象
pbmc_small <- pbmc_small  # Seurat 内置测试数据

# 运行 SCTransform
pbmc_small <- SCTransform(pbmc_small, verbose = FALSE)

# 看看结果
pbmc_small
# 输出应该包含 "SCT" 这个 assay

# 降维
pbmc_small <- RunPCA(pbmc_small, verbose = FALSE)
pbmc_small <- RunUMAP(pbmc_small, dims = 1:10, verbose = FALSE)

# 可视化
DimPlot(pbmc_small, group.by = "groups")

如果你能看到 UMAP 图，恭喜，环境搭好了。

避坑指南：如果 SCTransform 报错说找不到某些内部函数，八成是 SeuratObject 版本不匹配。我曾经遇到过 SeuratObject 被系统自动降级，导致 GetAssayData 的参数签名对不上。解决办法是强制更新所有包。

# 强制更新
update.packages(ask = FALSE, checkBuilt = TRUE)

4.7 最后说几句

环境搭建是枯燥的，但也是最重要的。你想想看，后面所有的标准化、批次校正、细胞聚类，都建立在今天这几行代码之上。

我个人建议：把 setup.R 脚本放在你的项目根目录里，每次开新项目都跑一遍。这样可以保证所有项目的基础环境一致，避免“我明明装了啊，怎么这个项目跑不起来”的尴尬。