【macOS】n8n 安装配置笔记

1. 安装 n8n 方法对比

方法一：通过 Homebrew（macOS 推荐）

# 添加 n8n 的 Homebrew 源
brew tap n8n-io/n8n

# 安装 n8n
brew install n8n

注意：如果遇到链接冲突，可以：

# 移除已存在的 n8n 链接
rm '/usr/local/bin/n8n'

# 强制链接
brew link --overwrite n8n

方法二：通过 npm 全局安装

# 先确保 Node.js 版本正确
npm install -g n8n

方法三：通过 Docker（最简化）

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  n8nio/n8n

2. Node.js 版本管理

nvm 常用命令

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

# 重新加载配置
source ~/.zshrc

# 查看已安装版本
nvm ls

# 安装特定版本
nvm install 18.17.0    # n8n 推荐版本
nvm install 20         # LTS 版本
nvm install 22         # 当前稳定版

# 切换版本
nvm use 18.17.0

# 设置默认版本
nvm alias default 18.17.0

# 删除不需要的版本
nvm uninstall 23.11.0

n8n 支持的 Node.js 版本

• ✅ 推荐: v18.17.0
• ✅ 支持: v20.x.x
• ✅ 支持: v22.x.x
• ❌ 不支持: v23.x.x（当前安装的错误版本）
• ❌ 不支持: v16.x.x（已过时）

3. 安装过程中的问题解决

问题1：Node.js 版本不兼容

错误信息：

Your Node.js version 23.11.0 is currently not supported by n8n.
Please use Node.js v18.17.0 (recommended), v20, or v22 instead!

解决方案：

# 1. 检查当前版本
node -v

# 2. 安装支持的版本
nvm install 18.17.0
nvm use 18.17.0

# 3. 验证版本
node -v  # 应该显示 v18.17.0

问题2：Homebrew 链接冲突

错误信息：

Could not symlink bin/n8n
Target /usr/local/bin/n8n already exists.

解决方案：

# 方案1：移除冲突文件后重新链接
rm '/usr/local/bin/n8n'
brew link n8n

# 方案2：强制覆盖链接
brew link --overwrite n8n

4. n8n 基本使用

启动 n8n

n8n start

启动成功信息

n8n ready on 0.0.0.0, port 5678
Version: 1.64.3

Editor is now accessible via:
http://localhost:5678/

配置文件位置

# 用户配置目录
~/.n8n/config

# 数据存储目录
~/.n8n/

5. 最佳实践建议

版本管理策略

1. 开发环境：使用 nvm 管理多个 Node.js 版本
2. 生产环境：使用 Docker 确保环境一致性
3. 团队协作 ：在项目中添加 .nvmrc 文件指定 Node.js 版本

推荐的安装流程

# 1. 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

# 2. 安装正确的 Node.js 版本
nvm install 18.17.0
nvm use 18.17.0

# 3. 通过 npm 安装 n8n（最简单）
npm install -g n8n

# 4. 启动 n8n
n8n start

检查清单

• Node.js 版本是否正确（v18.17.0/v20/v22）
• n8n 是否成功安装
• 端口 5678 是否可用
• 配置文件是否正确加载

6. 常见配置调整

修改默认端口

# 启动时指定端口
n8n start --port=8080

# 或修改配置文件 ~/.n8n/config
n8n start --config=/path/to/config

生产环境配置

# 以服务方式运行
n8n start --tunnel

# 启用 HTTPS
n8n start --ssl-key=key.pem --ssl-cert=cert.pem

总结

成功安装 n8n 的关键在于：

1. 使用正确的 Node.js 版本（v18.17.0 是最佳选择）
2. 解决路径冲突问题（特别是使用多种安装方式时）
3. 使用 nvm 管理 Node.js 版本，便于切换和测试

推荐使用 npm 全局安装 方式，配合 nvm 管理 Node.js 版本，这是最灵活且问题最少的方案。