干了这么多年自动化流程设计我陆陆续续给团队和客户装过几十次n8n坦白说最花时间的从来不是配置工作流本身而是第一步——把环境装得干净、跑得稳。很多刚开始接触n8n的朋友卡在安装上要么遇到权限问题要么装完不知道数据存在哪要么升级一次就把老流程搞挂了。这篇就把macOS上两种主流安装方式Homebrew和npm从头到尾拆开讲清楚包括每个命令干了什么、为什么这样选、以及装完之后的初始化配置。无论你是第一次接触n8n还是之前被报错劝退过照着走基本不会翻车。1. 装之前先搞清楚n8n是什么为什么非要在macOS本机装n8n是一个可自托管的可视化工作流自动化工具你可以把它理解成一个带图形界面的流程编排中心。它通过节点Node连接不同的服务比如邮件、数据库、HTTP接口、飞书、企业微信、各类SaaS工具让数据自动流转替代重复的人工操作。早期很多人在n8n和同类产品之间纠结实际用过之后会发现n8n最大的优势是代码与可视化结合得很好——简单流程可以全靠拖拽复杂逻辑可以直接写JavaScript代码块不需要在两个工具之间来回切换。回到安装这个问题上。n8n官方提供的运行方式有好几种Docker容器、npm全局安装、Homebrew安装、桌面版应用还有云托管版本。如果你只是想在macOS上本地体验或者做一些个人自动化流程我建议直接选Homebrew或npm而不是Docker。原因是Docker在macOS上的资源占用比较大尤其是Apple Silicon之前的Intel芯片机器跑一个虚拟机层再跑容器风扇能转得跟起飞一样。而且Docker方式管理数据卷、端口映射对刚接触n8n的人来说多了一层理解成本。那为什么不用桌面版桌面版n8n其实很省心下载dmg双击就能跑但它的版本更新相对滞后而且它默认把自己封装成了一个独立应用后续如果你想把它作为常驻服务来管理比如开机自启、通过pm2守护进程反而不如命令行方式灵活。我个人的观点是如果你打算把n8n当做一个正经工具长期用而不是随便玩玩那就用Homebrew或npm装一个命令行版本它能让你对系统里发生了什么有完整的控制权排查问题也方便。macOS本机安装还有一个实际好处本地运行意味着没有服务器成本数据都在你的电脑里对隐私敏感的项目来说更放心。而且n8n的本地模式会使用SQLite数据库零配置装上就能跑不会像企业级部署那样需要先准备PostgreSQL或MySQL。对于入门阶段这就是最舒服的起点。等你真的跑起来了再考虑迁移数据库、部署到服务器完全不迟。2. 动手之前的准备工作三样东西没到位后面全是坑安装n8n之前我不建议直接上来就敲命令。花五分钟把环境梳理清楚能帮你避开后面90%的莫名其妙的问题。这一节我们分三步走确认macOS架构、搞定Homebrew、搞定Node.js环境。2.1 确认你的Mac芯片架构这决定了后面所有命令的差异Apple SiliconM1/M2/M3/M4系列和Intel芯片的Mac在终端执行某些命令时会有细微差别特别是在Node.js原生模块编译、Homebrew安装路径上。你可以用一行命令确认uname -m输出是arm64就是Apple Silicon芯片输出是x86_64就是Intel芯片。这个信息很重要因为后面无论是安装Homebrew还是n8n的依赖包都需要知道自己的架构。比如在Apple Silicon机器上Homebrew默认安装路径是/opt/homebrew而Intel机器上是/usr/local。如果你在网上搜安装教程发现路径对不上很可能就是架构不同导致的。另外还要确认系统版本。n8n对macOS的最低版本要求不算苛刻但我也遇到过在macOS 10.15上因为系统自带的Python或依赖库版本太旧导致npm安装失败的情况。如果你还在用Catalina或更老的系统建议先考虑升级系统实在升不了优先用Homebrew方式安装因为它对系统旧库的依赖相对少一些。2.2 Homebrew安装搭好macOS上的软件包管理地基Homebrew是macOS上最流行的包管理器它解决的核心问题就是软件装在哪、依赖怎么办、怎么卸载干净。n8n通过Homebrew安装时brew会帮我们处理Node.js运行时等依赖这是它相比npm方式最大的优势。如果还没安装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 /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)安装完成后运行brew -v确认版本。注意Apple Silicon机器上脚本最后会提示你把/opt/homebrew/bin加入PATH按提示操作就行。还有一个高频问题Homebrew新版本把核心仓库变成了独立仓库安装某些包时会触发brew update如果这个更新过程卡住或者很慢大概率是Git拉取远程仓库的网络问题。解决方式很简单在终端里设置代理环境变量如果你有可用的网络代理或者继续用上面提到的镜像源。这类问题的排查思路后面会单独细说。2.3 Node.js环境准备npm方式安装的前提用nvm更稳用npm方式安装n8n前提是系统里有Node.js。但是我不建议直接从官网下载pkg安装包因为Node.js版本迭代快n8n对Node版本有要求直接装一个全局版本将来升级或者切换项目会很痛苦。推荐的做法是先装nvmNode Version Manager再用nvm装指定版本的Node。nvm的安装方式很简单curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后需要重启终端或者source一下配置文件source ~/.zshrc然后用nvm安装Node.js。n8n当前版本对Node.js的要求是^18.10我们直接装一个稳定版nvm install 20 nvm use 20 nvm alias default 20把默认别名指到20版本这样以后新开终端也默认用这个版本。用node -v确认输出是v20.x。这里强调一下n8n不喜欢太新的Node版本某些奇数版本或者刚发布的偶数版本可能存在兼容性问题我踩过Node 21跑n8n直接报错的坑所以老老实实用LTS版本就好。3. 路线AHomebrew安装n8n全程记录与关键命令解读当你把Homebrew准备好了安装n8n本身就是一行命令的事brew install n8n但这一行命令背后做了很多事情不理解它出问题时你就不知道从哪下手。3.1 brew install n8n 到底装了什么执行这条命令时Homebrew会先检查它的依赖自动安装Node.js如果还没装的话、npm、以及n8n包本身。你可以看到终端里哗啦啦滚动很多日志最终提示安装完成。我实测下来的结果是Homebrew方式安装的n8n本质上还是通过npm全局安装的方式把包放到了node_modules里只不过Homebrew帮你处理了Node.js运行时和路径管理。安装完成后输入which n8n你大概率会看到输出的路径和npm方式完全一样都是/opt/homebrew/bin/n8nApple Silicon或者/usr/local/bin/n8nIntel。这说明什么说明Homebrew本质上就是在帮你管理npm的全局包但它额外保证了一个干净的Node环境。如果你希望锁定n8n版本或者想安装指定版本可以用brew search n8n brew info n8n第一条命令查看仓库里有没有这个包第二条命令查看当前版本和依赖信息。brew info里会显示类似stable 1.x.x的版本号这个就是当前可安装的版本。3.2 第一次启动n8n start 之后的日志怎么看安装完成后直接在终端输入n8n或者显式启动n8n start第一次启动时n8n会做几件事初始化配置文件、创建数据库默认是SQLite、启动Web服务。你会在终端看到类似这样的日志n8n ready on http://localhost:5678看到这行日志说明服务已经起来了。打开浏览器访问http://localhost:5678你会进入一个首次用户注册页面。这里要注意n8n的首次注册相当于创建管理员账号不是简单的登录一定要记住邮箱和密码尤其是n8n社区版不像云版有忘记密码的邮件重置功能密码忘了处理起来比较麻烦后面我在踩坑章节会细说处理方法。默认端口是5678如果你的8000或5678端口被其他程序占用了可以用--port参数指定其他端口n8n start --port56793.3 Homebrew服务模式让n8n在后台常驻用n8n start启动的问题是终端一关服务就停了。如果你希望n8n像系统服务一样在后台运行Homebrew提供了service子命令brew services start n8n执行这条命令后n8n会作为后台服务启动即使关闭终端它也不会退出。想要停止服务就执行brew services stop n8n查看服务状态用brew services list。但是这里我遇到过一个情况用brew services跑n8n重启Mac之后服务有时候不会自动恢复或者在升级n8n版本之后服务状态会变成error。我的建议是如果你需要常驻服务直接用pm2来管后面的章节会细讲这里不展开。4. 路线Bnpm安装n8n更适合开发者的原汁原味方式如果你已经是一个前端或后端开发者系统里本来就有Node.js环境那npm方式反而是更省事的一条路。4.1 配置npm镜像源解决国内网络问题npm官方源的下载速度在国内不算稳定尤其在安装n8n这种依赖很多的包时经常出现卡在fetchMetadata的情况。我的做法是先切换npm镜像源再安装n8n。查看当前镜像源npm config get registry如果输出不是https://registry.npmjs.org/说明之前配置过其他源。如果你是直连网络建议切换到国内镜像npm config set registry https://registry.npmmirror.com这里要提醒一句镜像源的选择不是越新越好。一些冷门镜像源可能更新不及时导致装不到n8n最新的补丁版本。我用下来最稳的就是npmmirror淘宝镜像它的同步频率高大版本基本不会滞后。如果你在npm install过程中遇到ETIMEDOUT或者ECONNRESET这类报错第一反应应该是网络问题先检查镜像源配置是不是对的而不是反复重试同一个命令。4.2 npm install -g n8n全局安装与版本锁定确认镜像源没问题后执行全局安装npm install -g n8n这个命令会把n8n安装到全局node_modules目录。全局安装的好处是n8n命令在终端的任何目录下都能直接使用不需要考虑本地依赖问题。安装过程中如果你是Apple Silicon机器偶尔会遇到node-gyp编译原生模块的报错因为某些依赖需要从源码编译。解决办法是先安装Xcode Command Line Toolsxcode-select --install如果已经装了但还是报编译错误试试清理npm缓存后重装npm cache clean --force npm install -g n8n --build-from-source--build-from-source会让npm从源码编译所有原生模块虽然慢一点但能解决很多奇怪的二进制兼容问题。我在M1 Mac上就因为这个原因折腾过半小时后来发现是node-gyp依赖的Python版本不对装了Command Line Tools之后自动匹配了正确的Python问题就消失了。如果你想锁定一个具体版本比如害怕最新版有坑可以这样装npm install -g n8n1.50.0装完后验证一下n8n --version能正常输出版本号说明安装链路是通的。4.3 npx n8n 和全局安装有什么区别还有一种快速启动方式是用npxnpx n8nnpx会在临时目录下载n8n并启动省去了全局安装这一步。它的好处是体验成本极低不会污染你的全局环境坏处是每次启动都会检查下载最新版启动速度慢而且无法持久化n8n配置到固定的全局路径。我的建议是如果你只是想看看n8n长什么样可以用npx;如果你确定要用它做项目请老老实实全局安装。因为npx方式下载的版本是浮动的最新版当n8n发布了一个不稳定的新版本时你用npx启动的可能恰好就是那个问题版本而全局安装时你可以用版本号锁定安全得多。5. 两种安装方式横评速度、体积、升级与卸载的实际差异很多人在装之前纠结到底用Homebrew还是npm这里我给出一个比较完整的对比表格然后逐个分析。对比维度Homebrew方式npm方式安装前置条件需要先装Homebrew需要先装Node.js/nvm安装时间首次较慢含依赖更新取决于npm镜像源速度版本管理brew自行处理依赖依赖系统Node环境常用安装命令brew install n8nnpm install -g n8n升级方式brew upgrade n8nnpm update -g n8n卸载方式brew uninstall n8nnpm uninstall -g n8n数据存储位置~/.n8n~/.n8n后台服务管理brew services start n8n自行配置pm2/launchd对系统的侵入性依赖Homebrew目录依赖Node全局目录适合人群不想碰Node环境的用户开发者/已有Node环境的用户从表格可以看出两者在数据存储位置上是完全一样的区别主要在于包管理方式。Homebrew最大的优势是依赖统一管理——它给你装一个独立的Node环境n8n在这个环境下运行不干扰你系统里其他项目的Node版本。如果你日常不写代码只是想用n8n做自动化这个优势太重要了。npm方式的优势则在于灵活。你可以用nvm随意切换Node版本遇到n8n兼容性问题时修改Node版本往往能快速解决。而且npm的包更新节奏比Homebrew快n8n发布新版本后npm源通常当天就能拉到Homebrew的formula更新则有一定延迟。关于卸载残留这也是一个很实际的考虑。brew uninstall n8n能干净地移除n8n本体但它不会删除~/.n8n目录下的数据库和配置文件——注意这里存着你所有的工作流和数据卸载前务必做好备份。npm方式的uninstall也是一样不会删除~/.n8n。这个目录的设计思路其实很好卸载再重装数据还在你不需要重新配置所有工作流。6. 安装完成后的必做配置数据目录、用户认证与进程守护很多安装教程到能看到网页界面就结束了但实际用起来你会发现还有几个关键配置直接影响体验。6.1 搞懂~/.n8n目录你的所有数据都在这里无论用哪种方式安装n8n的数据默认存储在用户目录下的.n8n文件夹里。你可以在终端输入ls -la ~/.n8n会看到类似database.sqlite、config、credentials等文件。database.sqlite是默认的SQLite数据库文件它保存了所有工作流、执行记录、用户信息。credentials文件也叫encrypted-credentials.json通常是这个名字用来保存各个服务的认证凭据但n8n对凭据做了加密不是明文。理解这个目录很重要因为备份n8n就是备份这个文件夹迁移到新电脑也是把这个文件夹拷过去。n8n有一个导出命令n8n export:workflow --all可以把所有工作流导出为JSON文件但完整备份还是直接拷贝整个目录最简单可靠。我建议你在安装完成后就手动备份一次这个目录后续每做一个重要项目备份一次养成习惯。6.2 用户认证初始化首次注册的管理员账号要用心记第一次打开http://localhost:5678时页面会要求你填写邮箱、姓名和密码进行注册。这个注册动作创建的是本地的用户凭证不是n8n云账号所以不会有验证邮件也不会有忘记密码的自动恢复流程。如果你忘了密码最直接的处理方式是修改用户数据库里的密码字段。n8n的密码不是明文存储的而是经过bcrypt加密所以不能直接改数据库文本。正确方式是使用n8n提供的一个内部命令n8n user-management:reset-password --emailyouexample.com注意这个命令要求n8n服务处于停止状态执行后会提示你输入新密码。如果执行时报错找不到命令检查你当前运行的n8n版本旧版本可能没有这个命令需要先升级。6.3 用pm2守护n8n进程让服务常驻、自动重启如果你想让自己部署的n8n更接近正式服务的状态不要用终端前台运行也不要依赖brew services而是用pm2来管理Node进程。pm2是Node.js生态里非常成熟的进程守护工具它的好处是进程崩溃自动重启、开机自启配置简单、日志集中管理。安装pm2npm install -g pm2启动n8npm2 start n8n --name n8n查看状态pm2 status设置开机自启pm2 startup pm2 savepm2 startup会在系统里注册一个launchd服务让pm2在开机时自动恢复之前守护的进程。我用这种方式跑了半年几乎没有操心过n8n进程的问题。日志查看用pm2 logs n8n排查报错比在终端里翻历史输出方便多了。7. 实战踩坑记录macOS安装n8n最容易翻车的5个问题这一节是这篇文章最有价值的部分。我把自己在macOS环境下安装和使用n8n时遇到过的坑全部列出来包括排查思路不是直接给答案而是让你能举一反三。7.1 任何来源被Gatekeeper拦截终端无法执行下载的安装包在macOS上从网上下载的未签名程序可能会被Gatekeeper拦截错误提示是无法打开因为无法验证开发者。这个问题在多发生在安装Homebrew或者后期安装某些依赖时。解决办法有两种一是右键点击应用选择打开二是在终端执行sudo spctl --master-disable关闭Gatekeeper限制谨慎操作不再建议长期关闭或者针对单个应用xattr -dr com.apple.quarantine 文件名去除隔离属性。顺着这个思路如果brew install n8n过程中卡在Downloading...阶段然后报curl错误很可能也是网络层面的拦截不一定是权限问题。这时候先检查网络再检查权限不要上来就关系统保护。7.2 npm安装时网络超时反复失败这是国内网络环境下最典型的问题。报错信息一般是npm ERR! network timeout、ETIMEDOUT、ECONNRESET。很多人的第一反应是重试但重试十次可能成功一次效率极低。正确的排查链路是先确认npm镜像源 → 再测试镜像源连通性 → 最后再重装。# 查看当前镜像源 npm config get registry # 测试镜像源连通性 curl -I https://registry.npmmirror.com如果镜像源配置是对的但依然超时可能是某些依赖被墙了比如二进制包这时候换一个备用镜像源试试npm config set registry https://registry.npmmirror.com如果还是失败在npm install时加--registry参数临时覆盖全局配置npm install -g n8n --registryhttps://registry.npmmirror.com7.3 升级n8n后老工作流不兼容操作UI突然变样n8n的版本迭代非常快大版本升级偶尔会带来破坏性更新比如节点属性改名、API接口变化。如果你用Homebrew方式升级到了最新版本打开旧工作流可能会发现某些节点配置校验失败或者节点类型找不到了。我的应对策略是升级前先备份~/.n8n目录。然后升级后如果发现问题立即用n8n export:workflow --all --outputbackup.json再导出一份工作流然后回滚版本# npm方式回滚 npm install -g n8n上一个稳定版本如果你使用的是Homebrew方式回滚稍微麻烦一点需要先卸载再安装指定版本brew uninstall n8n brew install n8n1.50.0 # 具体版本号以brew搜索为准还有一种情况升级后n8n数据库文件里的某个字段结构变了导致服务无法启动。这种问题往往伴随着数据库迁移失败日志。我的建议是千万别第一时间删数据库先把当前database.sqlite复制一份留底然后再启动如果启动失败看看是否可以配合N8N_DB_SQLITE_POOL_SIZE这类环境变量绕过问题实在不行才从备份恢复。7.4 端口冲突5678被其他程序占用n8n启动失败这个相对好排查。启动n8n时报EADDRINUSE说明5678端口被占用。可以用lsof查看是哪个程序占用的lsof -i :5678如果是旧版本的n8n还在后台运行把它停掉或者kill掉kill -9 进程号然后重新启动。如果是其他开发项目占用了端口直接用--port参数换端口即可。7.5 Apple Silicon机器上的Node原生模块编译失败在M1/M2/M3芯片的macOS上npm安装某些带原生模块的依赖时容易报node-gyp相关的编译错误比如fatal error: v8.h file not found或者No receipt for com.apple.pkg.CLTools_Executables found。这个坑其实不是n8n特有的是很多Node项目在Apple Silicon上的通病。排查链路是先确保Xcode Command Line Tools完整安装xcode-select --install再确认你的Node版本是LTS且支持当前架构。如果你是用Rosetta方式安装的旧版nvmNode的架构可能是x64安装某些原生模块时也会出问题。这种情况下建议彻底卸载nvm并重新安装arm64版本的Node环境。8. 写在最后我的安装习惯和一些掏心窝的建议按照我实际使用n8n这么久的经验这里总结一下我个人的安装习惯。如果是给不熟悉命令行的同事或者客户搭环境我会优先用Homebrew方式因为它的依赖隔离做得更好出问题的概率低。如果是给我自己的开发机装我会选择npm方式因为我本来就用了nvm管理Node版本多一个n8n只是npm i -g n8n一条命令的事而且将来用npm update -g n8n升级特别顺手。我的具体习惯是安装之前先跑一遍nvm ls和node -v确认环境干净安装之后第一件事不是开始建工作流而是把~/.n8n目录做个备份然后把n8n --version、端口、启动方式这三点记录下来写在自己的工具清单里。升级前也养成了先备份的习惯。这些动作听起来很琐碎但等你真的遇到升级后跑不起来、或者误删数据的时候就知道这个习惯有多值钱。最后再说一个很多新手容易忽略的点n8n服务本身跑起来之后你可以尝试用N8N_ENCRYPTION_KEY这个环境变量设置自己的加密密钥。默认情况下n8n会生成一个内置密钥但如果你需要把数据库迁移到其他机器或者和团队协作保持一致的自定义密钥会省掉很多凭据解密失败的问题。macOS上可以把它写到~/.zshrc里或者在启动服务时临时指定具体取决于你管理环境变量的习惯。安装是启动n8n之旅的第一步也是最不应该反复折腾的一步。把环境理顺了后面设计工作流、调试自动化脚本时才会有好心情。希望这篇教程能帮你少走一些弯路。