1. 项目概述：为什么在 Windows 上部署 BioClaw 值得花一整天时间折腾？
BioClaw 这个名字听起来像某个科幻电影里的生物武器代号，其实它是一个面向生物信息学领域的开源命令行工具集，核心功能是自动化处理高通量测序数据——比如从原始的 FASTQ 文件开始，自动完成质控（FastQC）、去接头（Trimmomatic）、比对（Bowtie2/BWA）、定量（featureCounts）、差异表达分析（DESeq2）这一整套流程。它不是图形界面软件，没有“下一步”按钮，靠 YAML 配置文件驱动，用 Node.js 编写，底层调用大量 Linux 原生生物信息学工具。而你手头只有一台装着 Windows 11 的笔记本，公司内网连不上 GitHub，IT 部门不给开管理员权限，连 PowerShell 执行策略都被锁死。这时候，“在 Windows 上部署 BioClaw”就不是一句技术口号，而是一场真实存在的生存挑战。
我去年帮一家三甲医院的生物信息科做本地化部署，他们所有终端都是 Windows，服务器是 CentOS 7，但科研人员日常分析必须在本机跑小样本预实验。我们试过 WSL2，结果发现医院电脑 BIOS 里 Secure Boot 死活关不掉，WSL2 安装直接报错；试过 Docker Desktop，又卡在 Hyper-V 启用失败，提示“此 Windows 版本不支持”；最后硬着头皮走纯原生 Windows 路线，踩了整整三天坑，才把 BioClaw 的claw run命令第一次成功打出SUCCESS: Pipeline completed in 4m 23s。这篇记录，就是把那三天的每一条错误日志、每一次重装、每一个被忽略的环境变量，全部摊开讲透。它不教你怎么优雅地写代码，只告诉你：当npm install报错ERR! code 1、当claw init提示Cannot find module 'child_process'、当bowtie2-build命令在 CMD 里显示“不是内部或外部命令”时，你该敲哪一行命令、改哪个配置、删哪个缓存文件夹。关键词里反复出现的Windows、BioClaw、Node.js v22，不是凑热度，而是精准锚定三个致命交汇点：操作系统层的路径分隔符和权限模型、工具链层的跨平台兼容性断层、运行时层的 Node.js 版本与原生模块 ABI 不匹配。如果你正坐在一台 Windows 电脑前，面前开着 VS Code 和一个空白的终端窗口，这篇文章就是为你写的——它不承诺“一键部署”，但保证你读完后，能亲手把 BioClaw 的齿轮咬合进 Windows 的系统齿槽里。
2. 核心思路拆解：为什么放弃 WSL/Docker，坚持原生 Windows 路线？
很多人看到“BioClaw + Windows”第一反应是：“上 WSL2 啊，一劳永逸”。这确实是官方文档里最常推荐的方案，但现实远比文档残酷。我在医院现场排查时，用systeminfo命令扫了 37 台终端，其中 21 台的 Windows 版本是 22H2，但 BIOS 设置里 Secure Boot 状态为 “Enabled and Locked”，IT 部门明确告知“不允许修改固件设置”；另外 9 台虽然能开启 WSL2，但wsl --install执行到一半就卡在Installing: Ubuntu，日志显示0x80370102错误——这是 Hyper-V 与第三方虚拟化软件（比如某些国产杀毒软件自带的沙箱）冲突的典型症状。更麻烦的是，BioClaw 依赖的 Bowtie2、Samtools 等工具，在 WSL2 里编译安装后，其二进制文件路径会落在/home/username/bioclaws/tools/bowtie2-2.5.3/这样的 Linux 路径下，而 BioClaw 的 YAML 配置文件里要求写绝对路径，一旦你把它写成C:\bioclaws\tools\bowtie2.exe，Node.js 进程在 WSL2 里根本找不到这个 Windows 路径。这种跨子系统路径映射的黑洞，会让整个 pipeline 在claw run第一步就崩溃。
Docker 方案同样存在结构性缺陷。BioClaw 的设计初衷是作为本地开发调试工具，它需要频繁读写用户目录下的input/和output/文件夹，而 Docker for Windows 默认的文件共享机制（通过\\wsl$\或\\host.docker.internal\）在 Windows 10/11 上有严重的性能衰减——实测处理一个 2GB 的 FASTQ 文件，Docker 容器内fastqc运行时间比原生 Windows 下慢 3.7 倍。更关键的是，BioClaw 的claw watch功能会监听输入目录的文件变化并自动触发分析，而 Docker 的 inotify 事件在 Windows 主机文件系统上根本不可靠，经常漏触发。我们曾用docker-compose up跑了 12 小时监控，结果只捕获到 3 次文件变更，而实际产生了 27 次。这不是配置问题，是 Windows 文件系统驱动层与 Linux 内核 inotify 机制的根本性不兼容。
所以最终选择纯原生 Windows 路线，不是妥协，而是基于三个刚性约束的主动决策：
第一，可控性。所有工具路径、环境变量、权限策略，都在 Windows 注册表和文件系统里明明白白，出问题能直接定位到C:\bioclaws\node_modules\下的某个.js文件，不用在 WSL2 的/mnt/c/和 Windows 的C:\之间来回跳转猜谜。
第二，性能确定性。Bowtie2 比对时内存带宽是瓶颈，原生 Windows 下 CPU 直接访问 DDR5 内存，而 WSL2/Docker 多了一层虚拟内存管理，实测bowtie2 --threads 8在原生环境下峰值内存带宽利用率 92%，在 WSL2 下只有 68%。
第三，运维一致性。医院信息科只维护 Windows 组策略，他们可以一键推送setx BIOCLAW_TOOLS "C:\bioclaws\tools"这样的环境变量，但没法给每台电脑单独配置 WSL2 的/etc/wsl.conf。
这条路的代价是：你必须亲手编译或寻找 Windows 兼容版的每一个底层工具，必须处理 Node.js 的node-gyp编译失败，必须绕过 Windows 权限模型对临时文件夹的限制。但好处是，一旦跑通，它就像一台老式柴油机——没有花哨的电子控制单元，但每次启动都稳稳当当，维修手册就写在你面前的 CMD 窗口里。
3. 环境准备与工具链搭建：Node.js v22 是唯一可行版本
BioClaw 的package.json文件里明确写着"engines": {"node": ">=20.0.0 <23.0.0"}，这意味着 Node.js v22.x 是当前唯一被官方验证过的稳定区间。网上很多教程还在推 v18，那是 BioClaw 早期版本的遗留物；而 v24 刚发布不久，其 V8 引擎升级导致node-gyp编译的原生模块 ABI 版本号从115跳到120，BioClaw 依赖的node-sqlite3模块尚未发布对应版本，强行安装会报Error: The module '\\node_modules\\sqlite3\\lib\\binding\\napi-v5-win32-x64\\node_sqlite3.node' was compiled against a different Node.js version。我试过用npm rebuild sqlite3 --runtime=node --target=24.16.0 --disturl=https://electronjs.org/headers强制重编译，结果在node-gyp configure阶段就卡死，日志里反复出现gyp ERR! stack Error: spawn C:\Python311\python.exe ENOENT——因为新版 node-gyp 默认找 Python 3.11，而医院电脑上只有 Python 3.9。
所以第一步，必须精准安装 Node.js v22.14.0（这是 v22 分支最后一个 LTS 版本）。不要去官网下载.msi安装包，那个安装器会默认勾选“自动配置 PATH”，但在某些企业域环境下，组策略会拦截 PATH 修改，导致安装后 CMD 里node -v仍显示旧版本。正确做法是：
- 访问 https://nodejs.org/download/release/v22.14.0/ ，下载
node-v22.14.0-win-x64.zip； - 解压到
C:\nodejs\（注意：路径不能含空格和中文，这是 Windows 下所有命令行工具的铁律）； - 手动编辑系统环境变量，在
PATH开头添加C:\nodejs\（必须加在开头，否则可能被旧版本覆盖）； - 关闭所有已打开的 CMD/PowerShell 窗口，重新打开，执行
where node，确认输出只有C:\nodejs\node.exe一行。
提示：如果
where node输出多行，说明旧版本残留。此时不要盲目删文件，先用reg query "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall" /s | findstr "Node.js"查注册表，再用wmic product where "name like 'Node.js%'" get name,version查已安装产品，最后用msiexec /x {ProductCode} /qn静默卸载（{ProductCode} 从上条命令获取）。这是企业环境中最干净的清理方式。
接下来是 BioClaw 依赖的底层工具链。BioClaw 的config.yaml模板里列出了 12 个必需工具，但并非所有都需要手动编译。我们按优先级排序：
- 必须手动下载 Windows 二进制版：Bowtie2（v2.5.3）、Samtools（v1.19）、FastQC（v0.12.1）、Trimmomatic（v0.40）。这些工具的官方 GitHub Release 页面都提供
.zip包，解压后把bowtie2.exe、samtools.exe等文件放入C:\bioclaws\tools\即可。特别注意 Bowtie2：官网只提供 Linux/Mac 版，Windows 版必须去 https://github.com/BenLangmead/bowtie2/releases/tag/v2.5.3 下载bowtie2-2.5.3-win-x64.zip，里面bowtie2-build.exe的签名日期是 2024-03-15，比某些第三方编译版更可靠。 - 可用 Chocolatey 一键安装：
choco install git curl wget。Chocolatey 是 Windows 下最接近 apt/yum 的包管理器，安装命令Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))。注意：执行前必须以管理员身份运行 PowerShell，否则choco install会因权限不足失败。 - 必须源码编译：
htslib（Samtools 的依赖库）。Samtools v1.19 的 Windows 二进制版已经静态链接了 htslib，但 BioClaw 的claw validate命令会调用htsfile工具检测 BAM 文件完整性，而官方 zip 包里没包含这个可执行文件。所以必须从 https://github.com/samtools/htslib/releases/tag/1.19 下载源码，用 Visual Studio 2022 的 x64 Native Tools Command Prompt 编译：
cd htslib-1.19 nmake -f Makefile.msvc HTSDLL=1编译成功后，htsfile.exe会生成在当前目录，把它复制到C:\bioclaws\tools\。
注意：编译 htslib 时若报错
fatal error C1083: Cannot open include file: 'zlib.h'，说明缺少 zlib 头文件。此时不要手动下载 zlib 源码，直接用choco install zlib安装，然后在Makefile.msvc里把ZLIBINC = $(ZLIBDIR)\include改为ZLIBINC = C:\ProgramData\chocolatey\lib\zlib\tools\include（路径以你实际安装位置为准）。这是 Windows 下 C 语言编译最典型的“头文件路径地狱”，必须亲手填平。
最后是环境变量配置。BioClaw 不会自动识别工具路径，必须显式声明。在 CMD 里执行：
setx BIOCLAW_TOOLS "C:\bioclaws\tools" setx BIOCLAW_INPUT "C:\bioclaws\input" setx BIOCLAW_OUTPUT "C:\bioclaws\output" setx PATH "%BIOCLAW_TOOLS%;%PATH%"这四条命令缺一不可。BIOCLAW_TOOLS告诉 BioClaw 到哪里找bowtie2.exe，BIOCLAW_INPUT/OUTPUT定义工作区，而最后一行把工具路径加到PATH，是为了让claw run内部调用的subprocess.spawn()能直接找到可执行文件——Node.js 的spawn函数在 Windows 下不继承父进程的PATH环境变量，这是个深埋的坑。
4. BioClaw 安装与初始化：绕过 npm 的代理与证书陷阱
现在进入 BioClaw 本体安装环节。你以为npm install -g bioclaw就完事了？在企业内网环境下，这行命令会触发至少三层拦截：
第一层是HTTPS 证书校验。很多医院内网使用自签名 CA 证书，而 Node.js 的https模块默认启用严格证书校验。当你执行npm install时，npm 会尝试连接https://registry.npmjs.org/，但内网 DNS 把这个域名解析到了内网镜像站，而镜像站的证书是 IT 部门自己签发的，Node.js 直接拒绝连接，报错UNABLE_TO_VERIFY_LEAF_SIGNATURE。
第二层是代理认证。即使你配置了npm config set proxy http://proxy.company.com:8080，内网代理往往要求 NTLM 认证，而 npm 的代理配置不支持自动传递 Windows 凭据，会卡在407 Proxy Authentication Required。
第三层是离线缓存污染。之前有人在其他电脑上用npm install下载过 BioClaw，把node_modules打包拷贝过来，但node_modules里包含大量*.node原生模块，它们是针对特定 Node.js 版本和 CPU 架构编译的。直接复用会导致Error: Module did not self-register。
所以必须采用“离线纯净安装”策略。步骤如下：
- 在外网 Windows 电脑上准备安装包：找一台能联网的电脑，确保已安装 Node.js v22.14.0，然后执行：
npm install bioclaw@latest --no-save注意：这里用--no-save是为了避免修改package.json，因为我们不需要保存依赖关系。执行后，node_modules\bioclaw\目录会被创建。
2.打包并传输：进入node_modules\bioclaw\目录，用 7-Zip 打包成bioclaw-offline.zip（不要用 Windows 自带压缩，它会丢失符号链接）。把这个 zip 文件拷贝到目标内网电脑。
3.在内网电脑解压并全局安装：在内网电脑上，新建C:\bioclaws\目录，把 zip 解压到C:\bioclaws\bioclaw\。然后打开 CMD，执行：
cd C:\bioclaws\bioclaw npm install -g .注意末尾的.，它表示“安装当前目录”，这是 npm 安装本地包的标准语法。
实操心得：
npm install -g .这步看似简单，但有个致命细节——它会读取bioclaw\package.json里的bin字段，创建全局命令链接。BioClaw 的package.json里写的是"bin": {"claw": "./bin/claw.js"}，这意味着claw命令会指向C:\Users\Username\AppData\Roaming\npm\node_modules\bioclaw\bin\claw.js。但 Windows 的AppData\Roaming\npm目录默认是隐藏的，且某些杀毒软件会监控这个路径，导致claw命令首次执行时被拦截。解决方案是在执行npm install -g .后，立即执行npm config set prefix "C:\bioclaws\npm-global"，然后重新安装：npm install -g . --prefix "C:\bioclaws\npm-global"。这样claw命令就会被创建在C:\bioclaws\npm-global\claw.cmd，路径完全可控。
安装完成后，验证是否成功：
claw --version如果输出bioClaw v3.2.1（具体版本号以你安装的为准），说明命令已注册成功。但别急着claw init，先执行：
claw doctor这是 BioClaw 内置的诊断命令，它会检查所有依赖工具是否在PATH中可访问、环境变量是否设置正确、临时目录是否有写入权限。它会输出一个彩色状态表，绿色表示 OK，红色表示失败。我遇到最多的问题是tmpdir检查失败——BioClaw 默认用os.tmpdir()获取临时目录，而在某些 Windows 企业环境中，这个函数返回C:\Windows\Temp，而普通用户对该目录没有写入权限。解决方案是手动设置：
setx TMP "C:\bioclaws\tmp" setx TEMP "C:\bioclaws\tmp"然后新建C:\bioclaws\tmp\目录，并右键属性 → 安全 → 编辑 → 添加当前用户，赋予“完全控制”权限。这是 Windows 权限模型的典型表现：系统 API 返回的路径，未必是你有权限写的路径。
5. 首次运行与配置文件详解：YAML 语法里的 Windows 陷阱
claw init命令会生成一个config.yaml模板，但这个模板是为 Linux 设计的，直接在 Windows 上用会触发一系列路径灾难。我们来逐行拆解这个文件里最危险的几处：
# config.yaml (Linux 版本) input_dir: "/home/user/bioclaws/input" output_dir: "/home/user/bioclaws/output" tools: bowtie2: "/home/user/bioclaws/tools/bowtie2-2.5.3" samtools: "/home/user/bioclaws/tools/samtools-1.19"问题一：路径分隔符。Windows 用反斜杠\，而 YAML 规范里反斜杠是转义字符。如果你写成input_dir: "C:\bioclaws\input"，YAML 解析器会把\b当作退格符（ASCII 0x08），把\i当作非法转义，直接报错while scanning a plain scalar。正确写法必须用正斜杠/或双反斜杠\\：
input_dir: "C:/bioclaws/input" # 推荐，简洁且跨平台 # 或 input_dir: "C:\\bioclaws\\input" # 也行，但冗长问题二：工具路径的可执行性。Linux 下bowtie2是一个没有扩展名的可执行文件，而 Windows 下必须是bowtie2.exe。BioClaw 的源码里，工具调用逻辑是spawn(tool_path, args)，如果tool_path指向C:/bioclaws/tools/bowtie2-2.5.3这个目录，Node.js 会尝试执行C:/bioclaws/tools/bowtie2-2.5.3.exe，显然不存在。所以必须精确到可执行文件：
tools: bowtie2: "C:/bioclaws/tools/bowtie2-2.5.3/bowtie2.exe" bowtie2_build: "C:/bioclaws/tools/bowtie2-2.5.3/bowtie2-build.exe" samtools: "C:/bioclaws/tools/samtools-1.19/samtools.exe"问题三：内存参数的单位混淆。BioClaw 的bowtie2配置项里有memory: "4G"，这在 Linux 下没问题，因为bowtie2命令行参数-X接受4G表示 4GB 内存。但在 Windows 下，bowtie2.exe的-X参数只接受纯数字（单位是 MB），4G会被解析为 0，导致比对时内存溢出崩溃。必须改成：
bowtie2: memory: 4096 # 单位是 MB，不是 GB问题四：临时文件路径的硬编码。config.yaml里有个temp_dir字段，默认值是/tmp。在 Windows 上，/tmp会被解释为C:\tmp，而这个目录通常不存在。必须显式指定：
temp_dir: "C:/bioclaws/tmp"完整的、经过 Windows 适配的config.yaml应该长这样（我已标注每一行的修改理由）：
# BioClaw 配置文件 - Windows 专用版 # 注意：所有路径必须用正斜杠 /，不能用反斜杠 \ # 注意：所有工具路径必须精确到 .exe 文件，不能只写目录 # 输入输出目录 input_dir: "C:/bioclaws/input" # 必须存在，且有读取权限 output_dir: "C:/bioclaws/output" # 必须存在，且有写入权限 temp_dir: "C:/bioclaws/tmp" # 必须存在，且有完全控制权限 # 工具路径 - 必须与你实际安装位置一致 tools: bowtie2: "C:/bioclaws/tools/bowtie2-2.5.3/bowtie2.exe" bowtie2_build: "C:/bioclaws/tools/bowtie2-2.5.3/bowtie2-build.exe" fastqc: "C:/bioclaws/tools/fastqc/fastqc.bat" # FastQC 是 .bat 文件，不是 .exe trimmomatic: "C:/bioclaws/tools/trimmomatic-0.40/trimmomatic-0.40.jar" # Trimmomatic 是 Java JAR samtools: "C:/bioclaws/tools/samtools-1.19/samtools.exe" featurecounts: "C:/bioclaws/tools/subread-2.0.6/featureCounts.exe" deseq2: "C:/Program Files/R/R-4.3.3/bin/Rscript.exe" # R 脚本路径，注意空格要加引号 # Bowtie2 配置 - 内存单位是 MB，不是 GB bowtie2: index: "C:/bioclaws/index/hg38" # 人类基因组索引目录，需提前用 bowtie2-build 创建 threads: 8 # 线程数，建议设为 CPU 逻辑核心数 memory: 4096 # 内存 MB 数，4GB = 4096MB # FastQC 配置 - Windows 下必须禁用 Java 图形界面 fastqc: no_gui: true # 关键！禁用 GUI，否则在无桌面会话时崩溃 threads: 4 # Trimmomatic 配置 - Java 参数必须显式指定 trimmomatic: java_opts: "-Xmx4g -Djava.io.tmpdir=C:/bioclaws/tmp" # Java 堆内存和临时目录提示：
fastqc.bat文件本身是个批处理脚本，它会调用java -jar fastqc.jar。但 Windows 的java.exe如果找不到JAVA_HOME，会去注册表里找 JRE 安装路径，而企业电脑上这个注册表项经常被 IT 部门清理。所以最稳妥的方式是，在config.yaml里把fastqc路径写成C:/bioclaws/tools/fastqc/fastqc.bat，然后在fastqc.bat文件开头手动添加：
@echo off set JAVA_HOME=C:\Program Files\Java\jre-11.0.22 set PATH=%JAVA_HOME%\bin;%PATH%这样就绕过了注册表查找，路径完全可控。
6. 首次 pipeline 运行与避坑指南：从claw run到SUCCESS
现在万事俱备，把你的 FASTQ 文件（比如sample_R1.fastq.gz和sample_R2.fastq.gz）放进C:\bioclaws\input\目录，然后执行：
claw run --config C:/bioclaws/config.yaml不出意外，你会看到终端里滚动出大量日志，格式类似：
[INFO] Starting pipeline for sample_R1.fastq.gz... [INFO] Running FastQC on C:/bioclaws/input/sample_R1.fastq.gz... [INFO] FastQC completed in 124s [INFO] Running Trimmomatic... [ERROR] Trimmomatic failed with exit code 1别慌，这是 Windows 部署中最常见的“首秀失败”。我统计了 37 次首次运行，其中 29 次卡在 Trimmomatic，原因高度集中：
根本原因：Trimmomatic 是 Java 程序，它依赖trimmomatic-0.40-adapters.fa这个适配器文件。BioClaw 的claw run逻辑会尝试从config.yaml的tools.trimmomatic路径向上回溯，找adapters/子目录。但trimmomatic-0.40.jar是独立下载的，它的adapters/目录并不在 JAR 包里，而是需要单独下载。官方文档没提这点，因为 Linux 用户习惯用apt install trimmomatic，那个包会自动安装适配器文件。
解决方案：
- 访问 https://github.com/timflutre/trimmomatic/releases/download/0.40/trimmomatic-0.40.zip ，下载完整 zip 包；
- 解压后，把
adapters/目录整个复制到C:\bioclaws\tools\trimmomatic-0.40\下； - 在
config.yaml里添加adapters_dir字段：
trimmomatic: adapters_dir: "C:/bioclaws/tools/trimmomatic-0.40/adapters"另一个高频问题是bowtie2-build创建索引失败。BioClaw 的claw init会生成一个index/目录，但bowtie2-build要求索引目录必须为空，且不能有同名的.bt2文件。如果之前失败过，C:\bioclaws\index\hg38下可能残留了hg38.1.bt2等半成品文件。此时bowtie2-build会报错Error: Index file hg38.1.bt2 already exists。解决方法不是删文件，而是用bowtie2-build的-overwrite参数，但这需要修改 BioClaw 源码。更简单的办法是：在config.yaml里把bowtie2.index指向一个全新的空目录，比如C:/bioclaws/index/hg38_v2，然后手动执行一次索引构建：
C:\bioclaws\tools\bowtie2-2.5.3\bowtie2-build.exe --threads 8 C:\bioclaws\reference\hg38.fa C:\bioclaws\index\hg38_v2\hg38注意：--threads 8必须加，否则单线程构建人类基因组索引要 40 分钟以上；hg38.fa是参考基因组 FASTA 文件，必须提前准备好；最后的hg38是索引前缀，bowtie2-build会生成hg38.1.bt2、hg38.2.bt2等文件。
当claw run终于打出SUCCESS: Pipeline completed in Xm Ys时，别急着庆祝。去C:\bioclaws\output\目录下检查输出文件：
sample_R1_fastqc.html和sample_R2_fastqc.html：用浏览器打开，确认质控报告正常；sample_R1_trimmed.fastq.gz：用gzip -t测试压缩完整性（Windows 下用7z t sample_R1_trimmed.fastq.gz）；sample.bam：用samtools view -H sample.bam | head -20查看 BAM 头，确认比对成功。
如果sample.bam文件大小为 0，说明bowtie2比对失败。此时看claw run日志里bowtie2那一段，最常见的错误是Error: Encountered internal Bowtie 2 exception (#1)，这几乎 100% 是因为bowtie2-build生成的索引文件权限问题。Windows 的 NTFS 权限有时会让bowtie2.exe无法读取.bt2文件。解决方案：右键C:\bioclaws\index\hg38\→ 属性 → 安全 → 编辑 → 添加Users组，赋予“读取和执行”、“列出文件夹内容”、“读取”权限，然后点击“替换子容器和对象的所有者”。
7. 常见问题速查表与独家排错技巧
以下是我在 37 台不同配置的 Windows 电脑上，总结出的 BioClaw 部署 Top 10 问题及秒级解决方案。每个问题都附带真实错误日志片段和一击必杀的命令。
| 问题现象 | 错误日志关键词 | 根本原因 | 一行解决命令 | 备注 |
|---|---|---|---|---|
claw命令未识别 | 'claw' is not recognized as an internal or external command | npm install -g未将claw.cmd写入PATH | setx PATH "%PATH%;C:\bioclaws\npm-global" | 必须重启 CMD 生效 |
bowtie2-build找不到输入文件 | Error: Could not locate input file: hg38.fa | bowtie2-build在当前工作目录下找文件，而非config.yaml里写的绝对路径 | cd C:\bioclaws\index\hg38 && C:\bioclaws\tools\bowtie2-2.5.3\bowtie2-build.exe ..\..\reference\hg38.fa hg38 | bowtie2-build的工作目录很关键 |
fastqc报java.awt.HeadlessException | Exception in thread "main" java.awt.HeadlessException | FastQC 尝试启动 GUI，但 Windows 服务会话无桌面 | 在fastqc.bat开头加set _JAVA_OPTIONS=-Djava.awt.headless=true | 比--no_gui参数更底层 |
samtools读取 BAM 报错 | EOF marker is absent. The input is probably truncated. | Windows 的curl下载的 BAM 文件末尾少了 EOF 标记 | curl -L -o sample.bam "http://example.com/sample.bam"改为Invoke-WebRequest -Uri "http://example.com/sample.bam" -OutFile sample.bam | PowerShell 的Invoke-WebRequest更可靠 |
claw run卡在Waiting for lock... | Waiting for lock on C:\bioclaws\output\.lock | BioClaw 的文件锁机制在 Windows 上失效，.lock文件残留 | del C:\bioclaws\output\.lock | 删除锁文件后重试 |
featureCounts报Segmentation fault | featureCounts.exe: Segmentation fault | Subread 的 Windows 版本与 Node.js v22 的内存模型冲突 | 下载subread-2.0.6-win64.zip而非subread-2.0.6.zip | 必须用 win64 专用版 |
Rscript找不到DESeq2包 | Error in library(DESeq2) : there is no package called ‘DESeq2’ | R 的library路径未包含 BioClaw 的 R 包目录 | Rscript -e "install.packages('DESeq2', repos='https://cloud.r-project.org/')" | 在 R 交互模式下安装 |
claw watch不触发分析 | No file change detected | Windows 的fs.watchAPI 对网络驱动器和 OneDrive 同步文件夹不可靠 | 把input/目录移到本地 SSD，如C:\bioclaws\input | 必须用本地物理磁盘 |
npm install报gyp ERR! stack Error: spawn python.exe ENOENT | gyp ERR! stack Error: spawn python.exe ENOENT | node-gyp找 |
