1. 为什么在ARM64 Linux上装Node.js和Yarn会是个“坑”最近在折腾一台树莓派4B打算把它变成一个轻量级的Web开发服务器。机器是ARM64架构系统装的是Ubuntu Server 22.04 LTS。我的想法很简单装个Node.js再配上Yarn包管理器就能在上面跑一些前端构建任务或者Node.js服务了。听起来是个标准操作对吧但真动起手来我发现从官方源直接apt install nodejs版本老得让人心碎想用NodeSource的安装脚本又得仔细核对架构支持至于Yarn官方文档的安装命令在ARM上也可能“水土不服”。这一套流程下来远没有在x86_64的服务器上那么顺畅。这其实反映了一个普遍问题随着ARM架构在服务器、边缘计算和开发板如树莓派、NVIDIA Jetson上的普及很多我们习以为常的开发工具链安装流程都需要根据新架构的特点进行微调。Node.js和Yarn作为现代JavaScript开发的核心在ARM64平台上的安装虽然最终都能搞定但中间涉及到源的选择、二进制包的兼容性验证以及权限配置等细节如果踩不准点很容易浪费时间。这篇文章我就结合自己的实操经历把在Linux ARM64系统上安装Node.js和Yarn的几种主流、可靠的方法梳理清楚并重点分享那些容易忽略的验证步骤和避坑要点。无论你用的是树莓派、AWS Graviton实例还是其他ARM64服务器这篇指南都能帮你高效、稳定地完成环境搭建。2. 安装前的核心准备理清版本与源的选择逻辑在动手敲命令之前花几分钟搞清楚“装什么”和“从哪装”能避免后续很多麻烦。这不仅仅是ARM平台的问题但在ARM平台上尤为关键。2.1 Node.js版本选择LTS还是Current对于生产环境或需要长期稳定的项目无脑选择最新的LTS长期支持版本。你可以访问 Node.js官网 查看当前的LTS版本号比如写作时的20.x。LTS版本会获得长达数年的安全更新和维护这是服务器环境的基石。对于个人开发或想尝鲜最新特性的环境可以考虑Current版本。但请注意在ARM生态中最新版本的二进制包发布有时会比x86平台稍晚几天或者某些非常用架构的构建可能临时缺失。因此在ARM平台上我更倾向于选择已发布一段时间的LTS版本其生态支持通常最为完善。2.2 安装源决策系统包管理器 vs NodeSource vs 二进制包这是ARM64安装的核心决策点每种方式各有优劣系统包管理器如apt优点最简单一条命令sudo apt install nodejs即可。与系统集成度好。缺点版本极其陈旧。例如Ubuntu 22.04官方源中的Node.js版本可能是12.x或16.x远落后于当前生态。且更新缓慢无法灵活选择版本。结论除非你的应用强依赖特定旧版系统包否则不推荐作为主要方式。NodeSource二进制源优点这是社区最推荐的方式。它提供了持续维护的、多版本的Node.js DEB/RPM软件包仓库。你可以轻松安装特定大版本如18.x,20.x并且能通过系统包管理器进行升级和管理兼顾了版本新和易管理。注意点需要手动将NodeSource的仓库源添加到你的系统。你需要确保所选的NodeSource版本支持arm64架构主流版本都支持但最好确认一下。结论大多数情况下的首选方案平衡了易用性、版本控制和维护性。直接下载二进制存档tarball优点最灵活完全独立于系统包管理器。可以从Node.js官网直接下载对应linux-arm64的.tar.xz文件解压到任意目录如/usr/local或$HOME即可使用。缺点需要手动处理环境变量PATH且后续升级需要手动重复此过程无法自动更新。结论适合需要多版本并行、或有严格环境隔离需求的场景例如通过nvm工具管理或者系统无法添加外部源的情况。对于Yarn情况类似。自从Yarn 2Berry之后官方推荐的安装方式是使用CorepackNode.js 16.10内置或直接下载独立版本。我们将主要采用Corepack的方式因为它最现代且与Node.js版本绑定。2.3 环境检查与依赖确认在开始安装前请打开终端执行以下命令来确认你的系统环境# 1. 确认系统架构 uname -m输出应为aarch64。在Linux语境下aarch64和arm64通常可以互换指代64位ARM架构。# 2. 更新系统现有包列表无论采用哪种安装方式都建议先做 sudo apt update sudo apt upgrade -y# 3. 安装一些可能需要的编译工具和基础依赖为后续可能操作做准备 sudo apt install -y curl wget git build-essentialcurl或wget用于下载安装脚本或二进制包build-essential包含GCC等编译套件虽然Node.js二进制包不需要编译但某些Node.js原生插件node-gyp可能会用到。3. 方案一通过NodeSource仓库安装Node.js推荐这是最接近“一键安装”体验且保持良好可维护性的方法。我们将使用NodeSource提供的自动化脚本来添加仓库并安装。3.1 下载并执行NodeSource安装脚本NodeSource为不同发行版提供了安装脚本。以安装Node.js 20.x LTS版本为例# 使用curl下载脚本并执行 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -命令分解与注意事项curl -fsSL-f失败时不显示HTTP错误-s静默模式-S在静默模式下显示错误-L跟随重定向。这是一个安全且通用的下载参数组合。sudo -E bash --E参数表示保留当前用户的环境变量如http_proxy传递给sudo执行的环境这在某些网络配置下很重要。脚本会以root权限运行负责添加NodeSource的GPG密钥和APT仓库源。重要提示务必从官方地址deb.nodesource.com获取脚本。你可以先访问https://deb.nodesource.com/setup_20.x查看脚本内容以确认其安全性。该脚本会自动检测你的发行版和版本并配置正确的仓库。3.2 安装Node.js脚本执行成功后你的APT源列表里就已经添加了NodeSource的仓库。现在可以直接安装sudo apt install -y nodejs这个nodejs包来自NodeSource仓库版本就是你刚才脚本指定的20.x。3.3 验证安装安装完成后必须进行验证以确保二进制文件是兼容的ARM64版本并且运行正常。# 检查Node.js版本和架构 node --version # 应输出类似v20.15.0 node -p process.arch # 应输出arm64 # 检查npm版本Node.js安装包通常自带npm npm --version # 应输出对应版本号如10.7.0 # 运行一个简单的JS代码测试 node -e console.log(Node.js on ARM64 is working!)如果process.arch输出arm64并且命令都能成功执行那么恭喜你Node.js已经正确安装。4. 方案二使用二进制存档Tarball进行安装如果你不想添加第三方源或者需要将Node.js安装到自定义目录例如没有sudo权限的用户目录这种方法很合适。4.1 下载正确的二进制包前往 Node.js官方下载页面 找到你想要的版本例如v20.15.0然后选择Linux Binaries (ARM64)对应的.tar.xz文件。通常名字类似node-v20.15.0-linux-arm64.tar.xz。在终端中你可以使用wget直接下载# 进入一个临时目录例如 /tmp cd /tmp # 下载二进制包请将URL替换为实际找到的最新LTS版本链接 wget https://nodejs.org/dist/v20.15.0/node-v20.15.0-linux-arm64.tar.xz4.2 解压并部署到系统目录通常我们将Node.js安装到/usr/local目录这是存放本地安装软件的标准位置。# 1. 解压下载的包 sudo tar -xJf node-v20.15.0-linux-arm64.tar.xz -C /usr/local --strip-components1参数解释-xJfx解压J处理.xz压缩格式f指定文件。-C /usr/local指定解压目标目录为/usr/local。--strip-components1非常重要这会将压缩包内node-v20.15.0-linux-arm64/目录下的所有内容直接解压到/usr/local而不是先创建一个子目录。这样bin/,lib/,include/等文件夹就会正确放置在/usr/local下。4.3 验证与手动安装的路径处理解压后Node.js的可执行文件node,npm,npx已经在/usr/local/bin目录下。通常这个目录已经在系统的PATH环境变量中。你可以立即验证/usr/local/bin/node --version如果输出版本号说明安装成功。但为了能在任何地方直接使用node命令你需要确保/usr/local/bin在你的PATH中。通常它默认就在。你可以用echo $PATH查看。如果你安装到了其他目录比如$HOME/nodejs则需要手动将该目录的bin子文件夹添加到PATH中。可以将下面这行添加到你的shell配置文件~/.bashrc,~/.zshrc等末尾export PATH$HOME/nodejs/bin:$PATH然后执行source ~/.bashrc使配置生效。5. 安装Yarn包管理器有了Node.js之后安装Yarn就简单多了。自Node.js 16.10起官方推荐使用其内置的Corepack来管理Yarn以及pnpm的版本。Corepack是一个实验性工具但已经是管理包管理器版本的事实标准。5.1 启用Corepack如果你的Node.js是通过上述方法安装的版本16.10Corepack应该已经包含在内但可能默认未启用。# 启用Corepack sudo corepack enable这个命令会为yarn和pnpm在全局创建软链接指向Corepack管理的版本。5.2 安装并激活特定Yarn版本启用Corepack后你可以使用它来安装特定版本的Yarn。# 安装并激活最新的Yarn稳定版 sudo corepack prepare yarnstable --activate # 或者安装一个具体的版本例如 4.0.1 sudo corepack prepare yarn4.0.1 --activatecorepack prepare会下载指定版本的Yarn并将其设置为当前激活的版本。5.3 验证Yarn安装# 检查Yarn版本 yarn --version # 应输出类似4.0.1 # 检查Yarn的全局安装目录由Corepack管理 yarn global dir如果能看到版本号说明Yarn已经安装成功并且yarn命令可以全局使用。5.4 传统安装方法备选如果因为某些原因无法使用Corepack例如极老的环境也可以使用npm来全局安装Yarn 1.xClassic但请注意Yarn 1.x已进入维护模式。npm install --global yarn1安装后同样用yarn --version验证。但强烈建议在新项目中使用Corepack管理的Yarn 3或4版本。6. 关键配置、问题排查与性能调优环境装好了但要让它在ARM64设备上跑得顺畅还需要一些配置和问题排查经验。6.1 npm与Yarn的镜像源配置在国内网络环境下将包管理器的源切换到国内镜像能极大提升依赖安装速度。配置npm镜像以淘宝源为例npm config set registry https://registry.npmmirror.com/ # 验证配置 npm config get registry配置Yarn镜像 对于Yarn 2通过Corepack安装的镜像配置方式与Yarn 1.x不同需要在项目根目录或全局配置中设置npmRegistryServer。# 全局配置影响所有项目 yarn config set npmRegistryServer https://registry.npmmirror.com/ -g # 或在项目目录下执行只影响当前项目 yarn config set npmRegistryServer https://registry.npmmirror.com/6.2 常见安装问题与排查E: Unable to locate package nodejs(使用NodeSource时)原因NodeSource仓库添加失败或未生效。排查# 检查仓库列表是否包含nodesource ls /etc/apt/sources.list.d/ | grep nodesource # 应看到类似 nodesource.list 的文件 # 更新APT缓存 sudo apt update # 再次尝试安装解决重新运行NodeSource安装脚本注意网络连接和脚本下载完整性。运行node或yarn命令提示Command not found原因安装目录不在PATH环境变量中或软链接未创建。排查# 查找node可执行文件位置 which node # 或 find /usr -name node 2/dev/null | grep bin # 查看PATH变量 echo $PATH解决对于二进制包安装确保安装目录的bin子目录如/usr/local/bin在PATH中。对于Corepack安装的Yarn确保运行了sudo corepack enable。安装原生模块node-gyp编译失败原因ARM64平台上编译某些C插件可能需要额外的库或特定配置。解决确保已安装build-essential。对于更复杂的情况可能需要安装Python 3和node-gyp全局工具。sudo apt install -y python3 make g npm install --global node-gyp某些模块如bcrypt可能有预编译的ARM64二进制包确保使用最新版本的npm/yarn它们会优先选择预编译包。6.3 ARM64平台特有的性能考量与优化ARM64架构与x86在内存模型和部分指令集上存在差异虽然Node.js运行时本身是跨平台的但以下经验可能有助于获得更好体验内存与Swap树莓派等开发板内存有限如4GB或8GB。在运行大型构建如Webpack时容易内存不足。建议适当增加Swap空间。# 检查当前swap sudo swapon --show # 如果很小或没有可以创建一个2GB的swap文件根据磁盘空间调整 sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile # 为了永久生效将以下行添加到 /etc/fstab # /swapfile none swap sw 0 0使用更快的存储如果设备支持将系统运行在高速SD卡A2级别或USB 3.0 SSD上能显著改善npm/yarn安装依赖时的大量I/O操作速度。针对V8引擎的潜在优化Node.js的JavaScript引擎是V8。在ARM64上确保系统有较新的GLIBC版本以支持V8可能使用的现代CPU特性。保持系统更新sudo apt update sudo apt upgrade通常就能满足。监控资源使用使用htop或npm/yarn自带的--verbose标志来监控构建过程中的CPU和内存使用情况及时发现瓶颈。7. 进阶使用NVM进行多版本Node.js管理如果你需要在同一台ARM64设备上测试不同Node.js版本例如同时维护需要Node.js 18和20的项目那么nvmNode Version Manager是更好的选择。它完全在用户目录下操作不需要sudo权限。7.1 安装NVMNVM的安装是通过运行一个安装脚本完成的。同样建议先检查脚本内容。# 下载并运行安装脚本 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash安装脚本会将nvm仓库克隆到~/.nvm并将初始化代码添加到你的shell配置文件~/.bashrc,~/.zshrc等。安装后你需要重新打开终端或者运行以下命令使nvm生效source ~/.bashrc # 如果你使用zsh则是 source ~/.zshrc7.2 使用NVM安装和管理Node.js版本nvm会自动检测系统架构并下载对应的ARM64二进制包。# 列出所有可安装的远程版本 nvm ls-remote # 安装指定版本的Node.js例如20.15.0 nvm install 20.15.0 # 安装最新的LTS版本 nvm install --lts # 查看已安装的版本 nvm ls # 切换当前shell使用的Node.js版本 nvm use 20.15.0 # 设置默认版本新开终端生效 nvm alias default 20.15.07.3 在NVM环境下使用Yarn当你使用nvm切换Node.js版本时每个版本都有独立的全局npm。因此Yarn也需要在每个Node.js版本环境下单独安装或者继续使用Corepack。推荐方式在每个nvm Node.js版本中启用Corepack# 切换到某个Node.js版本 nvm use 20.15.0 # 在该版本环境下启用corepack并安装yarn corepack enable corepack prepare yarnstable --activate这样当你切换Node.js版本时对应的Yarn也会随之切换。8. 实战检验创建一个简单的项目并运行理论说再多不如实际跑一下。让我们用刚装好的环境快速创建一个Node.js项目并安装依赖验证整个工具链是否工作正常。# 1. 创建一个项目目录并进入 mkdir ~/my-arm-test cd ~/my-arm-test # 2. 初始化一个新的Node.js项目一路回车用默认值即可 npm init -y # 3. 安装一个常用依赖例如 express npm install express # 4. 创建一个简单的服务器文件 app.js cat app.js EOF const express require(express); const app express(); const port 3000; app.get(/, (req, res) { res.send(Hello from ARM64! Node.js ${process.version} running on ${process.arch}); }); app.listen(port, () { console.log(Example app listening on port ${port}); }); EOF # 5. 运行这个服务器 node app.js现在你可以从同一网络下的另一台机器用浏览器访问http://你的树莓派IP:3000或者在本机用curl localhost:3000应该能看到包含“Hello from ARM64! Node.js v20.x.x running on arm64”的欢迎信息。这说明从Node.js运行时到npm包管理整个JavaScript环境已经在你的ARM64系统上完美运行起来了。这个简单的测试涵盖了项目初始化、依赖安装和运行服务是验证环境健康度的有效方式。如果在任何一步出错可以根据错误信息回溯到前面的章节查找对应的配置或解决方法。