如果你最近在倒腾自动化工作流一定躲不开 n8n 这个名字。简单说n8n 就是一个开源的可视化工作流编排工具它能让不同应用之间互相触发、搬运数据、做判断只要你能想到的“如果 A 发生就自动做 B”大概率都能在工作流里拼出来。很多做运营、做开发、甚至自己折腾个人效率系统的人都是被它“本地跑得起来、源码在自己手里、节点随便写”这几点吸引过来的。这篇是 n8n 工作流入门系列的第二篇专门聊 macOS 上的安装。我自己在 MacBookM 系列芯片上把 Homebrew 和 npm 两条路都实际走了一遍过程中踩了不少坑Homebrew 源的问题、npm 权限报错、node 版本不兼容、启动后浏览器打不开等等这篇全部摊开来讲。目标很简单不管是完全没碰过命令行的新手还是想搞清楚两种方式区别的老手看完都能照着敲完把 n8n 跑起来。1. 安装前的准备先搞清楚你要装什么、装在哪1.1 n8n 是什么以及它到底解决什么问题在正式开始敲命令之前我建议先花一分钟理解一下 n8n 的定位。你可以把它理解成一个“带图形界面的自动化胶水工具”。它和 Zapier、Make原 Integromat这类产品做的事情类似但最大的区别在于n8n 可以完全部署在你自己的机器或服务器上数据不经过第三方平台节点Node数量不受限社区版免费而且支持用 JavaScript 写自定义逻辑。它解决的核心痛点就是“重复劳动”。比如你的业务里每天要手动把客户表单数据同步到表格再发一条通知到钉钉或 Slack再更新某个数据库记录——这类跨系统的多步流程n8n 都能串起来跑。更关键的是它内置了几百个现成的集成节点从常见的 HTTP 请求、Webhook 到各种数据库、邮箱服务、AI 平台基本覆盖了大多数人对“自动化”的想象。顺便说一句现在很多人把 n8n 和 AI Agent 搭配着玩比如在一个流程里接大模型做内容分类、做意图识别再根据结果走不同分支。这也是我在入门系列后续内容里要展开的方向。不过那都是后话机器都还没装好之前先别急着想这些花活。1.2 两种安装方式的本质差异Homebrew 还是 npm既然标题是“保姆级教程”那先把最基本的逻辑理清。Homebrew 是 macOS 上最流行的包管理器它安装软件的方式是下载预编译好的二进制文件由 Homebrew 统一管理装在哪、怎么升级、怎么卸载都有现成命令。npm 则是 Node.js 自带的包管理器n8n 本身就是用 Node.js 写的所以你也可以把它当作一个 npm 包来全局安装。这两种方式的区别用大白话讲是这样的Homebrew 方式更像“安装一个系统级应用”你不需要关心 Node.js 环境Homebrew 会帮你处理依赖装完直接敲n8n就能启动。npm 方式更像“安装一个开发工具”前提是你得有一个能用的 Node.js 环境装完后 n8n 作为全局命令运行。我用一张表把关键差异列出来你在选型时可以直接参考对比维度Homebrew 安装npm 全局安装前置依赖需要 HomebrewmacOS 常用需要 Node.js 环境安装命令brew install n8nnpm install -g n8n依赖管理Homebrew 自动处理依赖 Node/npm 管理升级方式brew upgrade n8nnpm update -g n8n卸载方式brew uninstall n8nnpm uninstall -g n8n适合人群想开箱即用、少折腾环境本身是前端/Node 开发者习惯 npm 生态这两个方式没有绝对的好坏。我自己在实际使用中更偏 npm 方式因为我对 Node 环境本来就比较熟而且 n8n 版本更新很勤npm 上永远是最新的。但如果你是第一次接触命令行、也不想装一堆开发环境Homebrew 方式确实更友好。1.3 动手前检查三件事芯片类型、系统版本、已装工具别说我啰嗦这一步真能帮你少踩 90% 的坑。macOS 机器分 Intel 芯片和 Apple SiliconM1/M2/M3/M4目前绝大多数新机器都是 Apple Silicon但很多老旧教程还是在讲 Intel 的路径两者在 Homebrew 的安装路径上是有差异的。打开终端运行下面两条命令把输出记一下uname -m sw_vers如果第一条输出是arm64那你的机器是 Apple Silicon如果是x86_64那就是 Intel。sw_vers会显示 macOS 的具体版本比如 14.xSonoma、15.xSequoia这个信息后面排查环境问题时很有用。接着检查你机器上已经装了什么工具分别运行brew --version node -v npm -v如果你看到命令找不到的提示比如zsh: command not found: brew那说明对应工具还没装。不用慌下面每一节我都会给出安装方法。检查完之后你心里就有数了是走 Homebrew 路线还是先补 Node 环境再走 npm 路线又或者两条路其实你都已经具备条件。这时候再做选择就是顺手的事而不是碰运气。2. 方式一Homebrew 安装适合不想碰 Node 的省心路线2.1 先搞定 Homebrew安装、换源、常见报错Homebrew 的安装命令官网那一行大家都熟但我实际安装时经常遇到网络拉胯的问题。不绕弯子直接说稳妥做法。如果还没装 Homebrew先试试官网标准命令/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这一步如果卡住不动或者提示连接失败多半是网络问题。我在重装系统后遇到过几次解决方案是用国内镜像源装这里以中科大源为例你也可以用清华源或阿里源export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.ustc.edu.cn/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.ustc.edu.cn/homebrew-core.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.ustc.edu.cn/homebrew-bottles设置好这些环境变量之后再运行官方安装命令下载速度会明显改善。装完 Homebrew 之后最好再跑一下brew doctor看一下环境是否健康如果有警告按提示处理就行。还有一个常见的位置问题Apple Silicon 机器上Homebrew 默认装在/opt/homebrew而 Intel 机器装在/usr/local。如果你发现终端敲brew找不到命令但明明已经安装成功了大概率是 shell 环境变量没加载。在~/.zprofile里确认有没有这么一行eval $(/opt/homebrew/bin/brew shellenv)没有的话加进去然后执行source ~/.zprofile。2.2 用 brew install n8n 完成安装Homebrew 环境没问题之后安装 n8n 其实就一条命令的事brew install n8nHomebrew 会自动拉取 n8n 及它依赖的 Node.js 运行时等相关组件整个过程是自动的你只需要等它跑完。如果一切顺利终端最后会显示安装完成的信息。安装完成后直接敲n8n --version如果能输出一个版本号比如1.x.x说明 n8n 已经就位。接下来启动它n8n或者更正式的写法n8n start看到终端输出里出现类似 “Editor is now accessible via: http://localhost:5678” 这样一行就说明服务已经起来了。打开浏览器访问http://localhost:5678你会看到 n8n 的初始化界面。这里要特别提醒一点Homebrew 方式装 n8nbrew 可能会依赖它自带的 node 版本。如果你机器上同时用 nvm 管理着另一个 node 版本两者之间一般互不冲突因为 brew 装的 n8n 用的是它自己的依赖环境。这个现象对新手来说有点困惑但实际使用中反而省心——你不需要担心系统 Node 版本把 n8n 搞崩。2.3 Homebrew 安装后的日常维护升级、卸载、数据目录很多人装完就完事了等 n8n 出新版本了才想起来要升级然后发现不会操作。这里统一说清楚。升级 n8nbrew update brew upgrade n8n卸载 n8nbrew uninstall n8n注意brew uninstall只卸载程序本身不会删除你的工作流数据。n8n 的所有数据——包括你创建的工作流、凭据、执行历史——默认都存在~/.n8n目录里。也就是说哪怕你把 n8n 卸了重装只要这个目录还在重新启动后一切照旧。所以如果你真想彻底清理需要手动处理这个目录rm -rf ~/.n8n这个操作不可逆执行前务必确认你已经不需要里面的数据了。另外Homebrew 卸载后如果发现/opt/homebrew下还有残留的日志或缓存可以用brew cleanup做一次清理。网上很多人问“homebrew卸载残留”其实就是指这些缓存文件它们不影响新安装但会占磁盘空间。3. 方式二npm 安装适合有 Node 基础的高自由度路线3.1 先搞定 Node.js 环境推荐用 nvm 管理版本npm 方式的第一步是确保你的机器上有一个“够用”的 Node.js 环境。n8n 对 Node 版本有要求安装前最好确认一下当前版本建议用 Node 20 LTS 或更高版本。如果你机器上还没装 Node我最推荐的方式是先用 nvmNode Version Manager装因为 nvm 可以让你在多个 Node 版本之间随时切换遇到版本兼容性问题时非常好用。安装 nvm 不需要单独下载直接跑官网那行命令curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash如果因为网络问题拉不下来同样可以通过 Homebrew 来装虽然 nvm 官方并不主推这条路但确实能在国内网络环境下省去不少麻烦brew install nvm装完之后按终端提示把 nvm 的加载脚本加到 shell 配置文件里一般是~/.zshrc然后重新加载source ~/.zshrc接着安装 Node 20 LTS 版本nvm install 20 nvm use 20验证一下node -v npm -v如果能看到版本号Node 环境就算准备好了。3.2 配置 npm 镜像源然后全局安装 n8nnpm 在国内的下载速度一直是痛点。安装 n8n 这种依赖很多的全局包时如果直接用官方源很容易卡在某个依赖上下载超时。我自己的习惯是装之前先换源。先看一下当前源npm config get registry如果输出的是https://registry.npmjs.org/建议换成国内镜像npm config set registry https://registry.npmmirror.com换完之后再执行全局安装npm install -g n8n这个过程视网络情况会需要几分钟。安装期间你会看到大量依赖包在滚动输出这是正常的。如果出现很多npm warn deprecated xxx的提示不用太紧张。比如node-domexception1.0.0这类被弃用警告通常来自间接依赖不影响 n8n 本身的运行。只要最终能看到类似added X packages in Ys的提示安装就算成功。安装完成后验证一下n8n --version如果提示找不到命令说明 npm 全局 bin 目录没有加到 PATH 里。可以用下面命令看一下 npm 的全局 bin 路径npm prefix -g然后把输出目录加到 shell 配置文件的 PATH 里。例如如果输出是/usr/local/bin那大概率已经在 PATH 里了如果输出是~/.npm-global就需要这样配置export PATH$HOME/.npm-global/bin:$PATH加完记得source ~/.zshrc再试一次。3.3 启动验证n8n 跑起来之后该看什么Node 环境没问题、npm 包也装好了启动方式就跟 Homebrew 方式一样n8n或者n8n start首次启动时n8n 会自动创建~/.n8n数据目录并初始化一个 SQLite 数据库。终端出现http://localhost:5678的提示后打开浏览器访问就行。如果你在 mac 上遇到端口被占用的报错可以换一个端口启动n8n start --port5679还有一点值得说npm 方式下n8n 的版本跟随 npm 源更新。如果你设置了 npmmirror 镜像源镜像同步可能会有几小时的延迟但整体影响不大绝大多数时候装到的都是比较新的版本。如果你特别在意第一时间用到新版可以临时切回官方源更新npm install -g n8nlatest4. 安装完成后的第一件事初始化、凭据与数据备份4.1 首次打开浏览器创建管理员账号无论你用哪种方式安装第一次访问http://localhost:5678时n8n 都会引导你创建一个管理员账号。这里想认真提醒一下管理员账号的信息会存在本地数据库中请不要用你常用的邮箱和密码也不要在公共网络环境里裸跑 n8n。填好邮箱、姓名和密码之后点击下一步n8n 会进入工作台主页。到这里你的 n8n 就算正式跑起来了。如果你是远程服务器上部署的 n8n第一次访问时要用 URL 参数指定管理员账号比如n8n start --tunnel不过这个场景偏运维本地安装的读者暂时不用管。后续如果哪天真要做“n8n企业级部署方案”我再单独写一篇那会涉及到 Docker、域名、HTTPS、反向代理这些东西不是今天这篇的范围。4.2 理解 credentials管理密钥和安全边界第一次打开 n8n 工作台很多人会被左侧一排节点搞得眼花缭乱然后随便拖一个 HTTP 节点出来发现还要填认证信息就直接卡住了。这里重点说 credentials凭据这个概念。n8n 的凭据管理逻辑和很多自动化平台不太一样它把每个服务的账号密码、API Key、Token 集中存储在~/.n8n里并对敏感字段做加密。你在配置某个节点时不需要在每个工作流里反复粘贴密钥而是新建一条 credential然后在节点里通过下拉框选中它。配置 credentials 的入口在 n8n 左侧菜单的“Credentials”区域。选择要连接的服务填入对应的密钥信息n8n 会测试连接是否成功。比如你后面要接 RAGFlow 做知识库相关的工作流在配置 RAGFlow 节点时就是把 API 地址和密钥填到 credential 里让多个工作流复用。这个设计很关键因为工作流一多密钥管理就容易失控。我见过很多人把所有密钥直接写死在 HTTP 请求节点里结果流程分享或导出时密钥跟着全部泄漏。正确做法是所有密钥全部放进 credentials节点只引用凭据名称。4.3 数据备份意识~/.n8n 目录是你的全部家当n8n 本地模式下全部家当都在这一个目录里。如果你在这个目录里折腾了很久、搭了不少工作流请一定养成定期备份的习惯。备份最简单的方式就是把这个目录打包存档tar -czf n8n-backup.tar.gz ~/.n8n恢复也很简单把备份文件解压回原路径即可tar -xzf n8n-backup.tar.gz -C ~需要注意的是备份前最好先把 n8n 停掉不然数据库文件可能处于写入状态恢复出来的一致性无法保证。如果你已经用了一段时间、工作流越来越复杂我建议把备份脚本加到 crontab 里定期执行这是自动化思维的第一步。### 4.4 两种安装方式如何切换数据迁移其实很容易 这里插一个很多人在后台问我的问题如果先用 Homebrew 装后来想换成 npm 方式数据会不会丢答案是不会因为数据都在 ~/.n8n它和安装方式没有关系。 切换方式很简单先用原来的方式停掉 n8nCtrlC把 ~/.n8n 目录临时改名备份然后用新方式重新启动一次确认能正常访问再把新生成的 ~/.n8n 删除将备份目录改回去。 命令大概是这样的 bash mv ~/.n8n ~/.n8n.bak # 用新方式启动一次自动生成新的 ~/.n8n # 确认没问题后 rm -rf ~/.n8n mv ~/.n8n.bak ~/.n8n这样操作之后你原来的工作流、凭据、执行历史全都还在。macOS 上最忌讳的就是用 sudo 强改文件权限这一点后面会详细说但先记住sudo rm -rf ~/.n8n这种组合拳绝对不要打。5. 安装阶段常见问题与排查实录速查表收藏向5.1 Homebrew 相关问题换源、权限、arch 不匹配Homebrew 安装 n8n 最常见的报错排第一的就是网络超时。这通常表现为Error: Download failed或者安装进度条长时间不动。解决办法前面已经说了换镜像源设置HOMEBREW_BOTTLE_DOMAIN后重试。第二个常见问题是Error: No available formula with the name n8n。如果你遇到这个先执行brew update更新一下本地 formula 索引再重新brew search n8n看看有没有对应包。正常情况下homebrew-core 仓库里是包含 n8n 的只是你的索引版本太旧搜不到而已。第三个问题相对隐蔽在 Apple Silicon 机器上装了 x86 版本的 Homebrew。这种情况多见于从 Intel 老机器迁移配置后直接恢复的时间机器备份导致/usr/local和/opt/homebrew同时存在命令优先级混乱。排查方法是分别跑/usr/local/bin/brew --version /opt/homebrew/bin/brew --version如果两个都能输出版本号那你的环境有点混乱了。建议保留/opt/homebrew下的版本把/usr/local里的残留清理掉不然以后装包时会出现架构混用、二进制验证失败的风险。最后一个问题就是权限。很多人在网上看到“macOS 终端完全没权限了”这类求助帖往往是之前用sudo chown -R 用户名 /usr/local或sudo chmod -R 777 /opt/homebrew强行改过权限导致系统文件属主错乱。遇到这种情况先别急着继续装 n8n优先修复权限在恢复模式下运行csrutil disable关闭 SIP进入系统后用diskutil resetUserPermissions /重置权限这条命令需要知道你的用户 ID处理完后再开 SIP。但说实话如果你没做过chmod -R 777 /这种高危操作大部分权限问题不至于走到这一步。换个干净的思路把 Homebrew 卸了重装往往比修权限快得多。5.2 npm 相关问题镜像源失效、权限报错、deprecate 警告npm 安装 n8n 时最让人崩溃的是装了很久最后报EACCES: permission denied。出现这个错误绝大多数情况是系统自带 Node 是 brew 装的全局安装路径指向了系统目录比如/usr/local/lib/node_modules而你的用户没有写权限。网上很多教程会让你用sudo npm install -g n8n但这不是最优解因为 sudo 会把全局 package 变成 root 所有以后升级同样要 sudo而且容易让整个环境权限越来越乱。我的建议很明确用 nvm 重装一个 Node 环境让 npm 全局路径落在用户目录下。这是持久方案一次配置以后再也不碰权限问题。第二个常见问题是镜像源配置了但不起作用或者想切回官方源却忘了地址。重新说一下查看当前源npm config get registry切回官方源npm config set registry https://registry.npmjs.org/切到 npmmirrornpm config set registry https://registry.npmmirror.com第三个并不是错误但会让新手很慌就是安装时刷屏的npm warn deprecated。比如开头提到的node-domexception1.0.0这个包在较新的 Node 版本中已经被原生 API 替代所以 npm 会提示你用它对应平台的原生实现但这只是警告不影响 n8n 使用。看到这类警告正常忽略即可不需要专门去修。5.3 n8n 启动失败端口占用、数据库锁、版本不匹配启动 n8n 时最典型的三个问题我一起说。第一端口被占用。终端报EADDRINUSE或者port 5678 already in use说明已经有进程占用了 5678 端口。用下面命令查一下lsof -i :5678然后用kill -9 PID结束占用进程或者干脆给 n8n 换个端口n8n start --port5679第二数据库锁。如果上次 n8n 没有正常退出比如直接把终端窗口关了、睡眠唤醒后卡死、或者系统崩溃SQLite 数据库可能会留下.lock文件导致启动时报database is locked。解决办法是停掉 n8n把~/.n8n下的锁定文件移走再重新启动。第三版本与架构不匹配。这个多见于 Apple Silicon 机器。如果你从某个第三方镜像源装了一个旧版 Node或系统里同时有多个 Node 版本n8n 启动时可能报Bad CPU type in executable。这个错误在 Mac 上很经典本质是装了 x64 的二进制在 arm64 环境里跑但也没走 Rosetta。解决办法确保用nvm安装了 arm64 的 Node重新执行nvm install 20 --lts覆盖安装再卸载重装 n8n。另外很多人忽略的是macOS 上如果终端 App 是 Rosetta 方式运行的也会影响底层的架构判断。在“访达 - 应用程序 - 实用工具”里找到“终端”右键“显示简介”看一下“使用 Rosetta 打开”是不是被勾选了。因为 n8n 只是运行在 Node 环境中的 JS 代码正常情况下对架构不敏感但 npm 安装的某些原生模块比如某些加密库会直接踩到这个坑。5.4 我的避坑心得装 n8n 前后的几条习惯最后分享几条经验都是踩过坑之后才总结出来的算不上什么惊天动地的技巧但真能帮你节省时间。第一装 n8n 从来不是终点装完之后配置“任何来源”的问题总会冒出来。macOS 默认只允许安装 App Store 和被认可的开发者应用第一次跑brew install或npm install -g时可能被系统拦截提示“无法打开因为 Apple 无法检查其是否包含恶意软件”。解决办法系统设置 - 隐私与安全性 - 安全性选择“仍要打开”或者在终端执行sudo spctl --master-disable打开“任何来源”选项。这个命令在很多教程里出现过不过要注意加了 sudo 之后你就在修改系统安全策略如果安全意识一般建议临时用一次就恢复回来。我自己的习惯是不开“任何来源”遇到拦截就右键手动打开以保持系统默认的安全级别。第二macOS 系统升级前最好先把 n8n 停掉。我在 macOS 大版本更新时吃过亏升级到新系统后 n8n 数据目录的权限被系统重置过导致启动失败。虽然按 5.2 的思路用diskutil resetUserPermissions能修但费力又费时。后来我养成了习惯系统升级前CtrlC停掉 n8n升级完启动之前先看一眼~/.n8n的文件属主是不是自己。第三n8n 日志非常有价值。如果启动后出现无法访问页面的问题先别去折腾浏览器缓存直接看终端输出的日志重点搜error、warn、EADDRINUSE、permission denied。n8n 的启动日志信息很全大多数问题都能在日志里定位到根因。如果你想持久化保存日志可以用重定向n8n start ~/n8n.log 21日志文件会一直累积后续排查时会省好多事。写在最后装完之后下一步玩点什么到这个环节n8n 应该已经在你的 Mac 上跑起来了。我个人的建议是先别急着配一堆节点花半小时把界面上的组件过一遍左侧的节点面板、中间的工作流画布、右上角的执行与调试按钮、底部的日志区。随便拖一个 Schedule Trigger 和一个 HTTP Request 节点试着让 n8n 每分钟去请求某个接口看执行记录里的输入输出长什么样。这个最小流程走通了你就对 n8n 的“触发 - 处理 - 输出”模式有了直观体感。接下来比较顺的练手方向是把日常杂事自动化比如接收邮件自动存到本地表格、监控某个网页关键词变化后发通知、定时跑一个脚本并把结果推送到聊天工具。这些场景不需要写复杂代码全程用内置节点就能搭完跑成功之后的成就感非常强。n8n 的进阶路径也很清晰当你需要接入 RAGFlow 这类知识库工具或者让 AI Agent 在工作流里根据上下文做决策时再去研究节点里的认证配置、Webhook 回调、错误重试这些高级选项就水到渠成了。按照我个人的经验安装阶段最大的价值不在于“装好了一个软件”而在于你通过这个过程理解了它依赖什么、数据存在哪、出现问题从哪里查起。这份手感后面用 n8n 搭建任何复杂流程时都会成为你最扎实的基础。