rea命令安装全解析：curl脚本与npm全局安装对比及PATH排查

1. 先把 rea 是什么、两种装法到底在装什么讲清楚rea 命令在我的日常工具箱里属于那种装一次就再也离不开的角色——它是一个命令行工具跑在终端里干的是项目初始化、资源构建、批量任务编排这类活儿常见的调用形态就是rea init、rea build、rea sync这几个子命令。不同团队语境下 rea 具体封装了哪些能力会不太一样但它的安装机制是高度通用的本文重点就放在rea 命令怎么装到机器上、装到哪儿、怎么让 shell 找得到它这条主线上命令本身的业务逻辑请对照你手头的项目文档。之所以值得单独写一篇是因为 rea 这类工具普遍提供两条分发通道一条是官方的 shell 安装脚本形如curl -fsSL https://.../install.sh | bash另一条是 npm 包走npm install -g rea。curl 脚本安装和npm 全局安装看起来都是敲一行命令就完事但它们在文件落点、PATH 暴露方式、权限模型、版本管理能力、可审计性上完全是两套逻辑。我见过太多人在 CI 里混用这两种方式结果本地能跑、流水线报command not found也见过有人一路sudo npm i -g最后把全局目录搞成 root 所有后面装什么都得 sudo。这篇内容面向三类人刚接手项目、连 rea 都没装上的新手需要把 rea 塞进 CI 镜像、要求可复现的运维或平台同学以及已经装上了但想搞清楚我这台机器上到底装了几份 rea、哪一份在生效的老手。下面从我自己的实操顺序讲起先盘环境再分别拆两条安装路径最后给一张能直接照着做决策的对比表和一份踩坑速查。1.1 rea 的两种发行形态决定了安装方式要理解安装过程先得知道 rea 这个可执行文件是怎么被生产出来的。主流的 CLI 工具走两条技术路线rea 属于两条都有覆盖的那种。第一条是原生二进制路线用 Go 或 Rust 写编译出来就是一个几十 MB 的单文件自带运行时扔到任何同架构的 Linux/macOS 上都能直接跑唯一的系统依赖是 C 库。这类产物最适合用 shell 脚本分发脚本判断你的系统和 CPU 架构从对应的下载地址拉一个rea-linux-amd64.tar.gz或rea-darwin-arm64.tar.gz解压建软链完事。第二条是Node 包装路线npm 上发布的包本身很小真正的二进制是在postinstall钩子里按process.platform和process.arch去下载对应的预编译产物。esbuild、swc 这类工具都是这么干的。所以你会发现npm i -g rea之后node_modules里没多少东西但rea跑起来飞快——因为它跑的根本不是 JS。这个背景很关键两种安装方式最终装到机器上的可能是同一个二进制差异全部在谁来下载、下载到哪、怎么挂到 PATH 上这三个环节。理解了这一点后面所有的行为差异都能推导出来不用死记。1.2 为什么同一个工具要维护两条分发通道我一开始也疑惑官方为什么不干脆只留一条路。实际用下来两条通道各自覆盖了对方不擅长的场景这不是冗余是互补。curl 脚本的强项是零前置依赖。一台刚装好的最小化系统可能连 Node 都没有但有 curl 就能装 rea。CI 镜像尤其吃这一套Dockerfile 里一行RUN curl -fsSL ... | sh比起先装 Node、再配源、再全局装包能省下几百 MB 和几十秒构建时间。它还能把安装目录定到你想要的地方比如/usr/local/bin或者某个用户目录下的~/.local/bin不需要额外的权限协商。npm 全局安装的强项是包管理生态自带的那套能力语义化版本约束、私有源、锁定文件、依赖树审计、npx免安装试跑。团队里如果已经统一用私有 npm 源做内部组件分发那 rea 顺理成章也从这个源走版本管控和审计日志是现成的。我自己电脑上两个都装过最后留下的是 curl 脚本装的版本原因是启动快、不跟着 Node 版本漂移。但给团队写 CI 的时候我用的是 npm 方式因为可以钉死版本号并且复用已有的私有源凭据。所以哪个更好这个问题本身就问错了该问的是我这个场景缺什么。2. 装之前先花三分钟盘环境能省下后面三小时我踩过的安装类问题八成不是安装器写错了而是环境前提不成立。命令报的错往往很含糊比如一个干巴巴的Segmentation fault或者No such file or directory实际上是架构不匹配或者 glibc 版本太低。所以现在我不论装什么 CLI都先跑一遍下面这套体检。2.1 系统、架构与 C 库三个必须确认的坐标第一件事是确认 CPU 架构。uname -sm会给出类似Linux x86_64或Darwin arm64的输出。这一步看着废话但 Apple Silicon 上跑 Rosetta 终端、或者 x86 服务器上装了 arm 镜像的情况并不罕见装出来的二进制一跑就Bad CPU type或者直接段错误。第二件事是确认 C 库类型这一点在容器环境里特别容易翻车。绝大多数 Linux 发行版用 glibc而 Alpine 这类精简镜像用的是 musl。如果 rea 的下载页只提供linux-amd64的 glibc 版本你在 Alpine 里装完执行会得到一个非常误导人的错误not found——明明文件就在那儿权限也对但动态链接器路径不存在shell 就报找不到。uname -sm ldd --version 21 | head -n 1 # glibc 系统会打印版本号 cat /etc/os-release | head -n 3 # musl 系统这里通常是 Alpine第三件事是磁盘和目录权限。df -h ~看一眼剩余空间二进制加上版本目录留个几百 MB 比较稳妥。然后确认你打算装的目录你有写权限——这一点会在第 4 章展开很多人栽在 npm 全局目录的属主上。2.2 Node 与 npm 版本矩阵以及 PATH 顺序这个隐形杀手走 npm 路线的话node -v和npm -v必须先看。rea 的 npm 包通常会声明engines字段低于要求的大版本会直接拒绝安装或者装完运行时报语法错误。Node 14 和 Node 20 之间的 ESM 行为差异足以让一个 CLI 起不来。比版本更容易被忽略的是 PATH 顺序。echo $PATH | tr : \n把路径一条条列出来你会看到/usr/local/bin、~/.local/bin、~/.nvm/versions/node/v20.x/bin这些东西的先后次序。先出现的目录里的同名可执行文件优先。这意味着你完全可能装好了新版本但 shell 一直执行的是半年以前遗留在/usr/local/bin里的旧软链然后你对着rea --version输出的老版本号怀疑人生。排查这种装完没生效的问题type -a rea比which rea好用得多。which只告诉你第一个命中的type -a会把所有命中的路径按优先级全列出来一眼就能看出是不是有多份在打架。改完 PATH 或者装完新版本后记得hash -r清一下 shell 的命令缓存否则 bash 还会拿着旧路径去执行。这个小动作我至少省过五次明明装好了却还是旧版本的困惑。2.3 网络与凭据的前置检查别等报错再查公司内网环境要额外确认两件事出口能不能到分发域名以及 npm 的 registry 指向哪里。npm config get registry打出来如果不是公共源说明你在用内部私有源那 rea 这个包在不在私有源里、有没有被同步过得提前问清楚。私有源没同步的情况下npm i -g rea会报 404报错信息看起来像包不存在实际是源的问题。HTTPS 拦截也是常见故障。有些企业网络会在中间做证书替换curl 会报SSL certificate problemnpm 会报UNABLE_TO_VERIFY_LEAF_SIGNATURE。这种环境不要图省事关掉校验——正确做法是把公司根证书路径通过NODE_EXTRA_CA_CERTS喂给 Nodecurl 则用--cacert指定。关校验相当于把下载内容的完整性拱手让人对一个要往 PATH 里塞可执行文件的安装过程来说这个风险不值得冒。提示curl 脚本安装的安全底线是先下载、再阅读、后执行。把curl ... | bash拆成curl -o install.sh和bash install.sh两步中间用less看一眼脚本里请求了哪些域名、往哪些目录写文件这个习惯值三分钟。3. 方式一curl 脚本安装的完整拆解先说这条路因为它的行为最透明——脚本是纯文本干什么都写在里面。3.1 安装脚本内部到底做了哪五件事我把 rea 的安装脚本从头读了一遍结构非常典型稳定版安装器基本都是这个流程第一步探测环境用uname -s和uname -m拼出平台标识映射成linux-amd64、darwin-arm64这样的下载键同时检测是否存在$HOME、是否在容器里、有没有tar命令。第二步确定版本如果命令行没指定版本就请求一个版本清单接口拿到 latest 标签对应的版本号。这一步是弱网环境下最容易卡住的地方脚本通常会带重试。第三步下载并校验拉取对应平台的压缩包同时拉一个.sha256校验文件本地算完哈希对比不一致直接退出。这一步是整条链路的信任锚点。第四步解压落盘一般是解到~/.local/share/rea/versions/v1.2.3/这种带版本号的目录里。这个设计我特别喜欢多版本可以并存切换版本就是改一下软链指向不用重新下载。第五步建软链 改 PATH在~/.local/bin/rea建一个指向具体版本目录里二进制的符号链接然后往~/.bashrc或~/.zshrc里追加一行export PATH$HOME/.local/bin:$PATH。有些安装器会问你要不要改 shell 配置文件非交互模式下默认改。理解这五步之后所有安装成功但用不了的问题都可以按顺序定位是下载失败、校验失败、解压失败还是 PATH 没生效。3.2 从下载到验证逐条命令的执行现场我习惯把整个过程拆成可回滚的几步而不是一条管道到底。# 1. 下载安装脚本不执行 curl -fsSL https://get.rea.example.com/install.sh -o /tmp/rea-install.sh # 2. 看一眼大小和哈希 ls -lh /tmp/rea-install.sh sha256sum /tmp/rea-install.sh # 3. 快速扫一遍脚本在请求什么 grep -nE curl|wget|https?:// /tmp/rea-install.sh | head -n 20 # 4. 执行锁定版本指定安装目录不改 shell 配置 bash /tmp/rea-install.sh --version 1.2.3 --dir $HOME/.local/bin --no-modify-path # 5. 手动把 PATH 加进去因为上一步加了 --no-modify-path echo export PATH$HOME/.local/bin:$PATH ~/.bashrc export PATH$HOME/.local/bin:$PATH hash -r # 6. 验证 command -v rea rea --version-fsSL这四个参数不是随便凑的-f让 curl 在 HTTP 4xx/5xx 时返回非零退出码而不是把错误页写成文件-s静默进度条-S在出错时仍然打印错误信息-L跟随重定向。少了-f最危险——服务器返回一个 404 页面脚本文件里装的是 HTML你bash一下会得到一堆语法错误还不如直接失败来得清楚。--no-modify-path这个参数是我强烈建议加的。让安装器自动往 shell 配置里写东西写对了没事写重了或者写进了一个你并不使用的 rc 文件比如你用 zsh 但它改了.bash_profile排查起来非常费劲。自己手写一行位置和内容都可控。3.3 版本锁定、目录自定义和离线安装--version是脚本安装里最值钱的一个参数。不指定版本意味着每次重装都可能拿到一个新版本对生产环境和 CI 来说这是不可接受的漂移源。把版本号写进 Dockerfile、写进运维脚本构建结果才可复现。--dir决定软链落在哪里。默认通常是~/.local/bin这个目录在很多发行版上默认不在 PATH 里所以安装器才要改 rc 文件。如果你的~/.local/bin已经在 PATH 里很多现代发行版确实如此那就省事了。放在系统级目录/usr/local/bin也可以但要 sudo而用 sudo 跑远程脚本是我最不建议的操作——脚本会以 root 身份执行任意逻辑写文件的属主也会变成 root后续普通用户升级时会遇到权限墙。离线场景比如内网构建机完全不通外网需要另一种玩法在一台能联网的机器上用同样的脚本配合--dir装好然后把整个版本目录打包拷到目标机器解压到相同路径再手工建软链。# 联网机器上打包 tar -czf rea-1.2.3-linux-amd64.tar.gz -C $HOME/.local/share/rea/versions v1.2.3 # 目标机器上还原 mkdir -p $HOME/.local/share/rea/versions tar -xzf rea-1.2.3-linux-amd64.tar.gz -C $HOME/.local/share/rea/versions ln -sfn $HOME/.local/share/rea/versions/v1.2.3/rea $HOME/.local/bin/realn -sfn里的-n别省当目标已经是软链时没有-n会顺着软链往目录里建结果变成bin/rea/rea这种诡异结构。3.4 升级与彻底卸载脚本装的版本升级重跑一次带新版本号的脚本就行旧的版本目录会留在原地。这既是优点也是缺点——方便回滚但攒久了占空间。我一般保留最近两个版本更早的手工删。卸载要清三处漏一处就会留下幽灵命令删版本目录、删软链、把 rc 文件里那行 PATH 注释掉。清理完hash -r再type -a rea确认已经没有残留。我见过有人只删了软链结果某天 PATH 被别的脚本重排直接指向了残留的旧版本目录跑出来一个半年前的行为debug 了半天。4. 方式二npm 全局安装的完整拆解换条路走。npm 全局安装看起来只有一行命令但它背后牵扯的目录结构比脚本安装复杂出问题的地方也更隐蔽。4.1 全局包到底落在哪prefix、root、bin 三个概念先把三个命令记牢这是排查一切 npm 全局问题的钥匙npm config get prefix # 全局安装的根前缀 npm root -g # 全局 node_modules 的实际路径 npm prefix -g # 全局 bin 目录的父级可执行文件软链在 $prefix/bin在 Linux 上默认prefix是/usr/local于是全局包在/usr/local/lib/node_modules/可执行软链在/usr/local/bin/。而如果你用 nvm 管理 Nodeprefix会变成~/.nvm/versions/node/v20.x.x全局包就跟着这个 Node 版本走——切到另一个 Node 版本之前全局装的 rea 就消失了。这个行为不是 bug是 nvm 的设计但第一次遇到的人基本都会懵。安装时 npm 做三件事把包解到$(npm root -g)/rea读包里的bin字段然后在$(npm prefix -g)/bin建一个软链指向包的入口脚本。如果这个包是 Node 包装型第 1 章说的第二种形态还会在postinstall阶段按平台下载真正的二进制这一步走的是 npm 脚本的网络通道可能和 npm registry 不是同一个域名。4.2 实操安装、锁版本、验证、切版本# 安装最新版 npm install -g rea # 生产环境请锁版本 npm install -g rea1.2.3 # 确认装了什么 npm ls -g --depth0 | grep rea # 验证 command -v rea rea --version想在不污染全局环境的前提下先试试某个版本npx是最优雅的方案npx rea1.2.3 --version它会把包下到 npm 的缓存目录里临时执行不写全局node_modules。我在给不熟悉的项目做兼容性验证时基本都用这一招试完不满意缓存清一下就行机器上不留痕迹。升级全局包用npm update -g rea但要注意它受语义化版本约束只会升到当前大版本内的最新。想跨大版本就老老实实npm i -g realatest。降级同理显式指定版本号即可npm 会覆盖安装。4.3 权限这件事别用 sudo 糊过去npm i -g报EACCES: permission denied是因为当前用户对/usr/local/lib/node_modules没写权限。网上一搜答案清一色是sudo npm i -g。我现在完全不这么干理由有三个。第一sudo npm会让包里的postinstall脚本以 root 身份执行等于把 root 权限交给一个第三方包的安装钩子风险敞口太大。第二装出来的文件属主是 root之后普通用户跑npm update -g又会被拒陷入每次都得 sudo的死循环。第三全局目录里混着 root 和普通用户的文件哪天想整体清理都下不去手。正确做法是把全局目录挪到用户家目录下mkdir -p $HOME/.npm-global npm config set prefix $HOME/.npm-global echo export PATH$HOME/.npm-global/bin:$PATH ~/.bashrc export PATH$HOME/.npm-global/bin:$PATH hash -r npm install -g rea1.2.3这套配置写进~/.npmrc后对当前用户永久生效不需要 sudo卸载重装随便折腾。团队里我会把这几行直接放进开发环境初始化脚本新人拉下来就跑省掉一轮装不上→搜到 sudo→埋雷的循环。还有个小坑如果你同时用 nvmnpm config set prefix会被 nvm 的版本切换覆盖掉一部分行为因为你设的是一个固定路径而 nvm 期望 prefix 跟着 Node 版本走。这种情况二选一——要么接受全局包跟着 Node 版本走要么关掉 nvm 的 prefix 干预别两边都想要。4.4 卸载、清理与残留检查npm uninstall -g rea npm ls -g --depth0 # 确认没残留 command -v rea # 应该返回空npm 卸载一般比较干净软链和包目录都会删掉。但有两类残留要手工处理一是 npm 缓存里的旧版本 tarballnpm cache verify可以做一致性校验并清掉损坏条目二是包装型 CLI 在~/.cache/rea/这类目录下留的下载缓存这部分 npm 不管得自己看du -sh ~/.cache/*找出来。5. 两种方式横向对比以及我在不同场景下的选型铺垫完了直接上对比。这张表是我自己在多个项目里实测加复盘整理的不是抄文档。对比维度curl 脚本安装npm 全局安装前置依赖只需 curl 和 tar需要 Node 与 npm且版本达标安装位置默认~/.local/share/rea/versions/可自定义$(npm root -g)/rea跟着 Node 前缀走暴露方式脚本建软链到~/.local/binnpm 建软链到$(npm prefix -g)/bin版本切换改软链指向多版本并存方便依赖 nvm 或反复重装切换成本高权限风险不加 sudo 则完全用户级默认前缀可能需要提权易被诱导用 sudo可审计性脚本是纯文本可逐行阅读包内容不可见postinstall 有执行权离线安装打包版本目录即可很直接需要npm pack或离线缓存链路长CI 友好度极高一行命令镜像体积小中需先装 Node 运行时与私有源集成不涉及天然复用现有 registry 与凭据启动速度直接执行二进制冷启动快包装型需定位二进制通常也很快升级便利性重跑脚本或rea upgradenpm update -g适合谁运维、CI、多版本并存、无 Node 环境团队统一分发、需要审计与版本约束5.1 三个典型场景的决策过程场景一本地开发机只装一次。我选 curl 脚本。理由很实在——我的 Node 版本会跟着项目走今天 18 明天 20npm 全局装的 rea 会随 nvm 切换时灵时不灵。脚本装的那份在~/.local/bin里稳如磐石跟 Node 完全解耦。场景二团队统一的开发环境容器。我选 npm 全局安装并且把版本号钉死在 Dockerfile 里。因为这个容器本来就要装 Node复用已有的私有源和凭据是零额外成本而且npm ls -g能直接看到装了哪个版本审计友好。场景三极简 CI 构建镜像。我选 curl 脚本。一个node:20-alpine基础镜像光运行时就有几百 MB而我只需要 rea 这一个二进制。用debian:bookworm-slim加一行脚本安装镜像能小一截构建快十几秒。这里要注意第 2 章说的 musl 问题Alpine 上要么找 musl 版本要么换 glibc 基础镜像。5.2 混装会出什么事以及怎么避免最坏的情况是两种方式都装了而且 PATH 顺序不确定。表现是版本号时高时低或者某个子命令忽然不认某个参数。判断依据很简单type -a rea输出两行就说明装了两份。想留下哪一份把另一份对应的软链或目录删掉即可别指望 PATH 顺序来决定——那东西会被各种 rc 文件、包管理器初始化脚本改写不稳定。我给自己的规矩是一台机器上只保留一种安装方式并且把选择写进团队的开发环境说明文档。看起来是小事但新人入职第一天遇到的第一个障碍往往就是我按文档装了但版本和同事不一样。6. 常见问题与排查实录这一节是我这几年攒下来的故障库按现象归类配排查路径。6.1command not found的四种不同成因这个报错太笼统了至少对应四种完全不同的原因必须分开看。第一种装成功了但 PATH 没生效。特征是ls ~/.local/bin/rea文件存在。处置export PATH...后hash -r或者干脆exec $SHELL -l重开一个登录 shell 让 rc 文件重新加载。注意改完 rc 文件后当前 shell 不会自动重读必须先source或重开。第二种软链指向了不存在的目标。ls -l ~/.local/bin/rea会显示一个红色的断裂链接通常因为版本目录被手工删了。处置重建软链或重装。第三种二进制存在但动态链接器缺失Alpine 上装 glibc 版本的典型症状。特征是./rea直接跑也报错file rea和ldd rea能看出端倪。处置换 musl 版本或换基础镜像。第四种npm 全局包跟着 nvm 版本切换没了。特征npm ls -g里空空如也。处置切回原来的 Node 版本或者改用用户级固定 prefix 方案。6.2 权限、架构与脚本被拦截的处理EACCES一律走第 4.3 节的用户级 prefix 方案别用 sudo。Bad CPU type或段错误先查uname -m确认下的是不是对应架构的包。脚本安装报Permission denied多半是/tmp挂载了noexec换个目录比如~/tmp再执行。还有一类容易被忽略curl报SSL certificate problem: unable to get local issuer certificate。这是企业网络做了证书替换走--cacert指向公司根证书npm 侧对应NODE_EXTRA_CA_CERTS。关掉校验能立刻解决但我不建议——安装脚本要往你的 PATH 里塞一个可执行文件这条链路的完整性值得多花五分钟配好证书。6.3 故障速查表现象最可能的原因快速处置rea: command not foundPATH 未包含安装目录type -a rea定位补 PATH 后hash -r版本号与预期不符机器上有多份 reatype -a rea全列删掉多余软链EACCES全局前缀属主是 root改npm config set prefix ~/.npm-global装完立刻报找不到动态链接器缺失musl/glibc 错配ldd rea确认换对应版本Bad CPU type架构不匹配uname -m核对下载包npm 404私有源未同步该包找源管理员同步或临时切公共源UNABLE_TO_VERIFY_LEAF_SIGNATURE企业证书拦截NODE_EXTRA_CA_CERTS指向根证书切 Node 版本后命令没了nvm 的全局包隔离切回原版本或改用固定 prefix安装脚本执行后无任何输出/tmp挂noexec或 curl 静默失败换目录执行去掉-s看报错离线机器装不上无法访问分发域名打包版本目录手工还原7. 几条用血换来的实操建议先说最值得强调的一条任何curl ... | bash都不要直接执行。我现在的固定动作是先-o落地sha256sum记一下眼睛扫一遍脚本里请求的域名和写入路径确认没毛病再执行。这个过程不超过三分钟但它能挡住供应链层面的大多数意外——你去执行一个从网上拉下来、内容完全不可见的脚本本质上是把机器的一部分控制权交出去。第二条是版本必须钉死不分环境。本地开发图省事装 latest 无所谓但只要进 CI、进镜像、进任何会重复执行的地方版本号就必须显式写出来。我遇到过最难受的一次事故是一个月前能过的构建突然挂了排查半天发现是上游发了个新的 latest行为有细微变化。把版本写死这个动作花十秒钟省一整天。第三条装完永远用type -a确认一次。不要相信装完就对了机器上残留的旧版本、包管理器埋的软链、PATH 里的意外目录都可能让实际执行的和你以为的不是同一个东西。这个动作我坚持了两年救回来的时间远超成本。第四条给自己写一个bootstrap脚本把安装命令、PATH 配置、验证步骤全放进去。换机器、重装系统、给新人配环境一条命令跑完。我那份脚本里还带了版本号和架构判断的分支ARM 的 Mac 和 x86 的服务器走不同参数。这个投入第一次做要半小时之后每次省二十分钟值。最后分享一个排查思路用在我遇到过的几乎所有装完不能用的问题上从我以为它装在哪和shell 实际找到的是哪个这两个点对着看。一边用ls确认文件真实存在于哪另一边用type -a看 shell 从哪找的两个答案对上了问题就没有了对不上差额就是病因。这个二分法比任何排查清单都管用因为它直接指向了文件系统和PATH 解析这两个唯一的事实来源。