简介：CAT12.7 版本安装包面向脑结构像预处理与皮层表面分析的神经影像学习者，适合跟随教程完成 T1 加权像分割、配准与表面重建，却因官方迭代而找不到旧版安装包的人群。压缩包共 822 个文件，约 222.93MB，主体为 312 个 .m 源码脚本与多平台 MEX 二进制，并配有 .nii 影像、.gii 表面、.annot 分区标注、.html 说明页及模板、掩膜与示例数据，目录完整，可直接放入 MATLAB 工具箱路径运行。内容覆盖预处理、皮层厚度与曲率计算、球形配准等模块，并附带 Schaefer 200/400/600 分区、aparc_a2009s、HCP MMP1 等图谱标注，便于按笔记复现实验、对照分区结果并排查版本差异。已有 1731 人学习下载，适合需要稳定复现旧版流程、补齐 T1 处理与表面分析工具链的读者。
1. 一次装错版本的翻车：CAT12.7 不是解压完就能跑
手上这个 CAT12.7 版本安装包，是典型的源码软件分发方式：解压出来一堆.m文件、模板目录、图谱目录，没有 setup.exe，双击不会有任何反应。我第一次装它时按普通源码包的套路走——解压到桌面，在命令行里addpath一下，敲cat12，界面还真弹出来了，于是我当场认定装完了。真正翻车是在跑第一个被试的分段时，进度条走到仿射配准那一段直接中断，报错就干巴巴一行找不到函数；换成一份修订号更新的 SPM12 重新解压，同样的数据一路跑到出报告。这套环境在脑结构影像的处理链里太常见了，配准、组织分割、VBM、皮层表面重建都靠它，装不对不会立刻报错，而是让你跑完一整批才发现结果对不上。下面按我实际装的顺序，把这套环境从头走一遍。
2. 环境清单：MATLAB、SPM12 和 CAT12.7 三者怎么对齐
2.1 三个依赖各自的版本下限
CAT12 本身不是独立程序。它是 SPM12 的一个工具箱，SPM12 又跑在 MATLAB 上，三层叠着。任何一层版本不搭，症状都是「能启动但跑不完」——最恶心的一种失败模式，因为界面看着一切正常。
CAT12.7 这一代对 SPM12 的修订号有个下限，低于这条线，CAT12 内部调用的一些 SPM 函数根本不存在，症状是跑到某一步突然 undefined。稳妥做法是用 r7771 之后的 SPM12 修订版。确认办法不玄学：SPM 官方分发包的 zip 文件名里就带修订号（形如spm12_r7771.zip），解压时看一眼目录名或压缩包名，比进 MATLAB 里猜快得多。安装包里如果带了 readme，以 readme 写的为准；手上存的还是三四年前那份spm12.zip的，别硬上，直接换新的。
MATLAB 这边，CAT12.7 建议 R2017b 及以上、64 位。我不建议为了跑 CAT12 去装最新版 MATLAB，新版本 MATLAB 对老 SPM 的兼容偶尔会出些说不清的问题；R2017b 到 R2021a 之间的版本我实际跑过，比较稳。位数一定要 64 位，32 位 MATLAB 在处理 1mm 分辨率的 T1 时会在分配内存那一步直接失败，而且报错信息跟内存不足长得一模一样，很容易带偏排查方向。
如果不想装 MATLAB（比如集群上没有许可证），CAT12 提供 standalone 编译版，走 MATLAB Runtime。这条路能省掉许可证，但换来一个新约束：Runtime 版本必须和编译时用的 MATLAB 版本严格对应，差一个小版本都可能起不来。装 standalone 之前，先把安装包里的启动脚本读一遍，脚本头部通常会写明它需要哪个 Runtime。
| 组件 | 建议版本 | 在链路里的位置 | 版本不对的典型症状 |
|---|---|---|---|
| MATLAB | R2017b 及以上，64 位 | 运行时 | 老版本函数缺失，batch 保存失败 |
| SPM12 | r7771 之后的修订版 | 配准与统计框架 | 跑到某一阶段 undefined function |
| CAT12 | 7 系列（本包即 7） | 分割与形态学处理 | 界面能开，处理中断 |
| MATLAB Runtime | 仅 standalone 需要 | 免许可证运行 | 版本不匹配时脚本静默退出 |
2.2 解压之后目录该摆在哪
先把安装包解开看一眼结构，这一步别省。解开后应该是一个cat12顶层目录，里面能看到cat12.m、一批cat_开头的脚本、模板和图谱目录，以及一个standalone子目录（如果你下的是带编译版的那份包）。判断包完整不完整，最简单的办法是看有没有spm_cat12.m——SPM 工具箱的挂载约定就靠这个入口文件，缺了它，放哪都识别不到。
目录摆放只有两种合法姿势：
第一种，塞进 SPM12 的 toolbox 下。SPM 启动时会扫spm12/toolbox/的每个子目录，发现带spm_<name>.m的就自动挂进路径。这是最省事的装法，也是我推荐给新手的：
/opt/tools/spm12/ ├── spm.m ├── tpm/ ├── toolbox/ │ └── cat12/ <- 整个 cat12 目录放这里 │ ├── spm_cat12.m │ ├── cat12.m │ └── ...第二种，把 cat12 放在任意位置，靠 MATLAB 的addpath手动挂。这种姿势适合一个 MATLAB 里要共存多套 SPM 的场景，但要自己管路径顺序，容易出岔子。
不管用哪种，“解压到桌面然后addpath桌面路径”都是错得最彻底的一种。桌面路径带空格、带中文用户名是常态，CAT12 批量写文件时对这些字符的容忍度很低，最后表现为输出目录少了一半文件，而日志里一句报错都没有——这种黑匣子式的失败最难查。
2.3 装之前先确认 MATLAB 能用命令行跑
这一步很多人跳过，然后在批处理脚本上卡半天。先在终端里确认 MATLAB 能非交互启动，并顺手拿到版本号：
# R2019a 及以后支持 -batch，适合无人值守的批处理 matlab -batch "disp(version); disp(computer)" # R2019a 之前的版本没有 -batch，用 -r 加 exit matlab -nodisplay -nosplash -r "disp(version); disp(computer); exit"-batch是 R2019a 之后才有的参数，它会自动加载启动脚本、执行完就退出，返回码也规范，适合塞进 shell 脚本里做流水线。老版本只能用-nodisplay -nosplash -r "..."，注意这条命令最后必须自己写exit，否则 MATLAB 会挂在后台不退出，占着许可证不放。
computer的输出要重点看，GLNXA64、MACI64、PCWIN64分别对应 Linux、macOS、Windows 的 64 位，看到PCWIN32之类的就直接换环境，后面所有步骤都白搭。
提示：服务器上同时装了多个 MATLAB 版本时，
which matlab确认一下实际调用的是哪一个，PATH 顺序错导致用了老版本的情况非常常见。
3. 安装落地：把 CAT12.7 解压进 SPM12 的 toolbox 目录
3.1 标准装法：放进 toolbox 再启动 SPM
我一般把工具统一放在/opt/tools或~/tools下，路径里不带空格、不带中文、不带版本号之外的符号。整个安装过程就是三条命令：
# 1. 解压到临时目录，先看结构对不对 unzip CAT12.7.zip -d /tmp/cat12_unpack ls /tmp/cat12_unpack # 2. 确认解压出来的顶层目录叫 cat12，再整体挪进 SPM 的 toolbox mv /tmp/cat12_unpack/cat12 /opt/tools/spm12/toolbox/cat12 # 3. 验证入口文件在不在，这条决定 SPM 能不能认出它 ls /opt/tools/spm12/toolbox/cat12/spm_cat12.m第一条命令解压到临时目录而不是直接解压到目标位置，是为了留一步人工确认。有些压缩包解开后是双层目录（cat12/cat12/），直接mv进去会变成toolbox/cat12/cat12/，SPM 扫描时就找不到入口文件，表现为菜单里根本没有 CAT12 这一项。
第二条命令用整目录mv而不是把里面的文件全拷过去，是为了保留目录结构。CAT12 的模板、图谱、表面数据都放在固定相对路径下，脚本里用fileparts(mfilename('fullpath'))拼绝对路径，目录层级一乱就全找不到。
第三条是整段安装里最值钱的一行检查。入口文件存在，SPM 才认；不存在，后面无论怎么调addpath都只是让人误以为装好了。
装完在 MATLAB 里启动 SPM：
% 启动 SPM12，启动过程中它会扫描 toolbox 目录 spm % 在 SPM 的界面里能看到 CAT12 菜单项，说明挂载成功 % 也可以直接在命令行启动 CAT12 主界面 cat12spm启动时会重新扫描一遍 toolbox 目录，所以放进去之后不需要手动addpath。这也是标准装法比手动挂路径可靠的地方：路径由 SPM 管，不依赖用户的 MATLAB 搜索路径配置，换台机器重新解压一遍就能复现。
3.2 独立装法：addpath 的顺序和 savepath 的坑
必须在同一台机器上共存多套 SPM 时，只能用独立装法。核心是路径顺序：先 spm12，后 cat12。SPM12 必须在搜索路径更靠前的位置，否则 CAT12 里调用的 SPM 函数会解析到另一个版本上去，症状是某些功能莫名其妙地报参数错误。
% 顺序不能反：SPM 先，CAT12 后 addpath('/opt/tools/spm12'); addpath('/opt/tools/spm12/toolbox/cat12'); % 确认解析结果，两条都应该指向你要用的那一份 which spm which cat12 % 保存路径，让下次启动自动生效 savepath;addpath默认是把新目录加到搜索路径的最前面，所以上面两行的实际效果是 cat12 排在 spm12 之前。要严格保证 SPM 优先，得写成addpath('/opt/tools/spm12', '-begin')这种显式形式，或者在加完 cat12 之后再把 spm12 加一次到最前。这种细节平时不出问题，一旦机器上装了两份 SPM 就会集中爆发。
savepath是最容易翻车的一步。它默认往userpath指向的目录写（用userpath命令可以查，通常是用户主目录下的Documents/MATLAB）。如果当前用户对那个位置没有写权限，savepath会报错退出，而很多人不看这条报错，以为路径已经存下了，下次重启 MATLAB 又得重来一遍。更糟的情况是往 MATLAB 安装目录写，需要管理员权限，写完还可能因为权限位不对导致整个 MATLAB 启动变慢。装完先userpath看一眼，确认能写再savepath。
3.3 用 startup.m 固化路径，别用 MATLABPATH
想在启动时自动挂好路径，工具链里有个常见但不推荐的做法：设MATLABPATH环境变量。这个变量会替换MATLAB 的默认搜索路径，而不是追加，一旦设了它，MATLAB 自带的工具箱可能就找不到了，最后表现为某个跟 CAT12 毫无关系的函数突然缺失，排查方向被彻底带偏。
我一般用startup.m。把文件放到userpath指向的目录下，MATLAB 每次启动会自动执行：
% ~/Documents/MATLAB/startup.m % 只在目录真实存在时才加路径，避免路径表里堆积无效项 spm_dir = '/opt/tools/spm12'; cat_dir = fullfile(spm_dir, 'toolbox', 'cat12'); if isfolder(spm_dir) addpath(spm_dir, '-begin'); end if isfolder(cat_dir) addpath(cat_dir, '-begin'); endisfolder是 R2017b 之后才有的函数，更老的版本换成exist(dir, 'dir')。加这层判断的意义在于：网络盘掉线、移动硬盘没插、目录被清理，这些情况下addpath会往路径表里塞一条无效项，MATLAB 启动时会逐条校验，路径表越长启动越慢，最后慢到让人怀疑机器坏了。
-begin参数把目录插到搜索路径最前面，配合先加 cat12 后加 spm12 的顺序，最终 spm12 排在最前，符合 CAT12 对底层框架的依赖关系。
4. 参数配置：cat12_defaults 里先改的五项
4.1 默认参数存在哪，为什么改了没生效
CAT12 的默认参数不是写死在代码里的，而是存在一个.mat文件里，由cat12_defaults系列函数负责读写。界面上改完参数，必须显式保存成默认值，否则只对当前这一次处理有效——这是新手最常踩的一脚：在界面上明明把「输出配准后的图像」勾上了，跑完发现目录里只有原生空间的文件，回头一看设置又变回默认了。
保存入口在 CAT12 主界面上，不同小版本的位置略有差别，通常在界面下方的按钮或 Tools 菜单里，找带「default」字样的那一项。点进去改完，记得点保存。
参数生效顺序是从上到下覆盖的：代码里的硬编码默认值 → 默认参数文件 → 当前 batch 里显式写的字段。所以排查「为什么我的设置没生效」时，先看 batch 里有没有把这个字段写死。
4.2 值得动的手术刀参数
下面这张表是我每次装完都会过一遍的项。不是每项都要改，但每项都得知道改了会怎样：
| 参数 | 默认倾向 | 调整建议 | 影响 |
|---|---|---|---|
| Affine preprocessing (APP) | 中等强度 | 数据质量差时调低，正常数据保持默认 | 影响仿射配准的严格程度，调太高会把正常变异压掉 |
| Registration method | SPM 标准 | 样本量大且要做组分析时用 Dartel | Dartel 需要先跑模板生成，多一步但组间对齐更好 |
| Surface and thickness | 关闭 | 不做皮层分析就关掉 | 打开后单被试耗时翻倍，还会多出一堆表面文件 |
| Output format | Native | 需要组分析时加 Normalized | 只输出原生空间，后面做 VBM 还得重跑一遍 |
| Skull stripping | 自动 | 数据颈部残留多时手动指定 | 去颅骨不准会直接影响分割质量 |
| nproc（并行数） | 1 | 按物理核数设，别超过 | 需要并行工具箱支持，设太大反而抢内存 |
APP 这一项值得单独说。它的作用是控制仿射预处理的强度，值越大配准越激进。有些教程会建议调到很高的值来「提高配准精度」，这在健康成人数据上可能没事，但遇到萎缩明显的图像，过强的仿射会把解剖结构强行拉到模板形状上，分割结果看着很漂亮，实际已经失真。我的习惯是保持默认，除非某批数据明确出现配准失败。
nproc 是并行处理的进程数，但它在没有并行计算工具箱的 MATLAB 上是无效的——设了也不会报错，只是仍然单线程跑，很多人以为开了并行结果速度没变，原因就在这里。设之前先确认工具箱可用，值按物理核数设，不要按逻辑核数，超线程在密集浮点运算里帮不上忙还会加剧内存竞争。
4.3 用 batch 固化一套可复现的参数
界面上点一遍只能跑一次，要做批量就得落到 batch。最省事的做法是在界面上配好一次，然后从菜单里导出 batch 或脚本，再回来改关键字段。导出之后，我一般只动这几行：
% 假设 batch 已经从界面导出到 matlabbatch 变量里 % 1. 指定输入数据，用完整绝对路径，不要用相对路径 matlabbatch{1}.spm.tools.cat.estwrite.data = { '/data/sub-001/anat/T1.nii' }; % 2. 并行进程数，没有并行工具箱时这一项无效 matlabbatch{1}.spm.tools.cat.estwrite.opts.nproc = 4; % 3. 配准方式：'spm' 为标准法，'dartel' 需要先准备模板 matlabbatch{1}.spm.tools.cat.estwrite.extopts.registration.method = 'dartel'; % 4. 是否输出表面与厚度，不做皮层分析就置 0，能省一半时间 matlabbatch{1}.spm.tools.cat.estwrite.output.surface = 0; % 5. 执行 spm_jobman('run', matlabbatch);第 1 行的路径必须写绝对路径。CAT12 内部会cd到数据目录下工作，相对路径解析出来的结果跟你预期的不一样，最典型的症状是输出文件散落到上一层目录去了。
第 3 行切到 dartel 之前，样本里必须已经跑过一遍模板生成，否则这一步会直接报找不到模板文件。做法是先用全部被试跑一次标准法，再用生成的结果跑模板，最后拿模板回来重新跑一遍完整流程。听起来绕，但这是 Dartel 的正常用法，不是配置错了。
第 4 行关掉表面估计是最容易见效的优化。皮层表面与厚度估计是整套流程里最耗时的一环，不做皮层形态学分析的项目完全没必要开。关掉之后单被试耗时能砍掉将近一半，磁盘占用也降下来一大截。
第 5 行的spm_jobman是 SPM 的批处理入口，它会按顺序执行 batch 里的模块。批量跑之前建议先拿一个被试单独试，确认输出目录结构符合预期，再放开跑全量——这是血泪经验，一次跑两百个被试才发现输出目录名全错了的滋味不好受。
5. 避坑与排查：五条踩过的坑和它们的解法
5.1 现象：SPM 启动了，但菜单里根本没有 CAT12
原因基本只有一个：SPM 扫描 toolbox 目录时没找到入口文件spm_cat12.m。常见于三种情况——解压出来是双层目录、cat12目录名被改过、或者文件拷贝时漏了隐藏文件导致目录不完整。
解决顺序是先ls toolbox/cat12/spm_cat12.m确认文件在，再确认目录层级是toolbox/cat12/而不是toolbox/cat12/cat12/。层级错了就整目录挪一层上去，别在里面手工挑文件。如果文件确实在但菜单还是不出现，在 MATLAB 里which spm_cat12看解析到哪个路径——解析到旧版本目录的话，说明路径表里还留着上一份安装的残留，用rmpath清掉再重启。
5.2 现象：跑分段跑到某一阶段突然 undefined function
这是版本不匹配的典型症状，而且报错的函数名往往跟 CAT12 一点关系都没有，看着像随机的。原因就是 SPM12 的修订号太旧，CAT12.7 调用的某个 SPM 内部函数在那个版本里还不存在。
解决没别的办法，换 SPM12。换的时候注意把旧目录整个删掉或改名，别只是把新目录放进去——两份 SPM 同时在搜索路径里，which spm解析到哪一份是不确定的，会出现「明明换了版本问题还在」的错觉。换完重启 MATLAB，spm('Ver')确认一次。
5.3 现象：同一份数据，两次跑出来的结果不一样
先别怀疑算法玄学，八成是路径问题。CAT12 的部分中间文件写在当前工作目录下，如果跑批的时候工作目录不同，读到的中间文件也不同，结果自然不一致。
解法是把处理脚本写死：每次运行前cd到一个固定的工作目录，所有输入输出都用绝对路径。跑批脚本开头加一行restoredefaultpath再重新addpath的做法我不推荐，那会把用户自己装的其他工具箱一起清掉，副作用太大。用which -all spm看一眼有没有重复解析，多数问题当场就定位了。
5.4 现象：输出目录里文件少了一半，日志里没有任何报错
文件名里带中文、空格或特殊符号。CAT12 生成输出文件名时是在原文件名基础上加前缀，原文件名里的特殊字符会原样带进输出路径，某些文件系统或工具链处理不了，写入就静默失败。
处理办法很土但有效：跑之前统一重命名输入数据，规则固定成sub-XXX_T1.nii这种纯 ASCII 加下划线的形式。批量重命名用一段小脚本就行，比事后从两百个被试里找哪几个失败了省事得多。.nii.gz压缩格式虽然能读，但我一般先统一gunzip再跑，读写路径上少一层解压逻辑，出问题的面就小一圈。
5.5 现象：跑到一半 Java heap space 或内存不足
MATLAB 的 Java 堆和内存在处理高分辨率 T1 时会吃紧，尤其是开了表面估计又并行跑多个被试的时候。报错分两种：Java heap space 是 JVM 堆不够，MATLAB 的 out of memory 是进程内存不够。
Java 堆在 MATLAB 的偏好设置里调，找 Java Heap Memory 那一项，往上加一档重启即可。进程内存只能靠减少并行数、或者换更大的机器解决。我的经验是把 nproc 设成物理核数的一半，再开表面估计，基本不会撞上内存墙——并行数设满看着很爽，实际上是几个进程同时抢同一块内存，反而更容易失败。
6. 装完验证：一张 T1 数据走完最小闭环
装完不做验证，等于没装。我的验证流程固定成三步，跑通这三步才认为环境可用。
第一步，确认挂载。在 MATLAB 里敲which cat12和which spm_cat12，两条都得指向你刚装的那份目录，指向别处就先清路径。
第二步，拿一张自己的 T1 数据走完整流程，不要用示例数据。单被试，跑标准法，不开表面估计，五分钟到半小时能出结果。跑完检查输出：
| 检查项 | 预期 | 不通过先看什么 |
|---|---|---|
mri/子目录 | 出现 p0、p1 开头的分割结果 | 输入文件名是否有特殊字符 |
report/子目录 | 出现 cat_ 开头的 PDF 报告 | 是否有写权限 |
| 报告里的图像质量评级 | 与肉眼判断一致 | 数据本身是否有伪影 |
| 同目录的 xml 文件 | 能被正常解析 | 磁盘是否写满 |
第三步，把报告打开看一眼。这一步最容易被跳过，但报告里的图像质量评级和分割叠加图是整套流程唯一的可视化验证——分割结果对不上，报告里的叠加图一眼就能看出来，比你去逐个打开 NIfTI 快得多。
注意：验证用的数据不要用示例数据。示例数据是挑过的，能跑通示例不代表你的真实数据能跑通，尤其是有金属伪影、运动伪影或者视野不全的数据。
从那以后我每次装完这套环境，都会强制走一遍这张单被试的最小闭环，跑通了才敢往集群上放批量任务。装工具这件事，验证的十分钟能省掉后面返工的一整天。希望帮到你。
本文还有配套的精品资源，点击获取
