本教程详细说明如何在 Mac M3 (Apple Silicon) 上安装和配置 N8N，使用 PostgreSQL 作为数据库。 当然 N8N还有docker方式安装，但是docker使用本地环境特别是在有安全要求的环境下会存在一定问题，网上mac 本地安装教程较少故汇总一篇
系统要求
- macOS (Apple Silicon M1/M2/M3)
- Homebrew 包管理器
- PostgreSQL 数据库
- Node.js 20.x
安装步骤
1. 安装 Homebrew（如果存在可跳过）
如果尚未安装 Homebrew，请先安装：
bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" 2. 安装 Node Version Manager (NVM)（如果存在可跳过）
NVM 允许您管理多个 Node.js 版本：
bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash 重新加载终端配置：
bash
source ~/.zshrc```
### 3. 安装 Node.js 20（如果存在可跳过）
N8N 在 Node.js 20 上运行最稳定：
```bash
# 安装 Node.js 20nvm install 20
# 设置为默认版本
nvm alias default 20
# 验证安装
node --version # 应显示 v20.x.x 4. 创建项目目录
bash
mkdir ~/my_n8ncd ~/my_n8n```
### 5. 初始化项目并安装 N8N
```bash
# 初始化 npm 项目
npm init -y
# 安装最新版 N8Nnpm install n8n@latest
# 安装 dotenv 用于环境变量管理
npm install dotenv 6. 配置 PostgreSQL （如果存在可跳过）
6.1 安装 PostgreSQL（如果尚未安装）
bash
brew install postgresqlbrew services start postgresql```
#### 6.2 创建 N8N 数据库
```bash
# 以 root 用户创建数据库
psql -U root -h localhost -c "CREATE DATABASE n8n;" 7. 配置环境变量
创建 .env 文件配置数据库连接：
bash
cat > .env << 'EOF'# Database Configuration
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=localhost
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_DATABASE=n8n
DB_POSTGRESDB_USER=root
DB_POSTGRESDB_PASSWORD=
# N8N Configuration
N8N_PORT=5678
N8N_PROTOCOL=http
N8N_HOST=localhost
# Enable task runners (recommended)
N8N_RUNNERS_ENABLED=true
# Optional: Set timezone
GENERIC_TIMEZONE=Asia/Shanghai
EOF 8. 创建启动脚本
创建 start.sh 文件：
bash
cat > start.sh << 'EOF'#!/bin/bash
# Node.js 20 is now the default version
# Parse command line arguments
DEBUG_MODE=false
for arg in "$@"
do
if [ "$arg" = "debug" ]; then DEBUG_MODE=true echo "Debug mode enabled" fidone
# Load environment variables from .env file
export $(cat .env | grep -v '^#' | xargs)
# Set log level based on debug mode
if [ "$DEBUG_MODE" = true ]; then
export N8N_LOG_LEVEL=debug export N8N_LOG_OUTPUT=console echo "Log level set to: debug"fi
# Extract and set N8N API configuration from .mcp.json
if [ -f ".mcp.json" ]; then
export N8N_API_URL=$(python3 -c "import json; data=json.load(open('.mcp.json')); print(data['mcpServers']['n8n-mcp']['env']['N8N_API_URL'])" 2>/dev/null) export N8N_API_KEY=$(python3 -c "import json; data=json.load(open('.mcp.json')); print(data['mcpServers']['n8n-mcp']['env']['N8N_API_KEY'])" 2>/dev/null) if [ ! -z "$N8N_API_URL" ] && [ ! -z "$N8N_API_KEY" ]; then
echo "Loaded N8N API configuration from .mcp.json" echo "N8N_API_URL: $N8N_API_URL" echo "N8N_API_KEY: [SET]" fifi
# Create logs directory if it doesn't exist
mkdir -p logs
# Generate log filename with timestamp
LOG_FILE="logs/n8n_$(date +%Y%m%d_%H%M%S).log"
echo "Starting N8N at $(date)" | tee "$LOG_FILE"
echo "Log file: $LOG_FILE" | tee -a "$LOG_FILE"
if [ "$DEBUG_MODE" = true ]; then
echo "Debug mode: ENABLED (Log level: debug)" | tee -a "$LOG_FILE"else
echo "Debug mode: DISABLED (Log level: default)" | tee -a "$LOG_FILE"fi
if [ ! -z "$N8N_API_URL" ] && [ ! -z "$N8N_API_KEY" ]; then
echo "API Configuration: $N8N_API_URL (API Key: [SET])" | tee -a "$LOG_FILE"fi
echo "----------------------------------------" | tee -a "$LOG_FILE"
# Start N8N in background with output redirected to log file and console
npx n8n 2>&1 | tee -a "$LOG_FILE" &
# Save the PID of the tee process
TEE_PID=$!
# Get the actual n8n process PID (child of npm/npx)
sleep 2 # Wait for n8n to fully start
N8N_PID=$(ps aux | grep "[n]ode.*n8n" | grep -v "task-runner" | awk '{print $2}' | head -1)
if [ ! -z "$N8N_PID" ]; then
echo "$N8N_PID" > logs/n8n.pid echo "N8N started with PID: $N8N_PID" | tee -a "$LOG_FILE"else
echo "Warning: Could not find N8N process PID" | tee -a "$LOG_FILE"fi
# Wait for the tee process to finish (when n8n exits)
wait $TEE_PID
# 赋予执行权限
chmod +x start.sh 9. 配置 package.json 脚本
编辑 package.json，添加便捷脚本：
json
{
"name": "my_n8n", "version": "1.0.0", "main": "index.js", "scripts": { "start": "n8n", "update": "npm update n8n && npm install" }, "keywords": [], "author": "", "license": "ISC", "description": "", "dependencies": { "dotenv": "^17.2.1", "n8n": "^1.106.3" }}
启动 N8N
使用启动脚本（推荐）
bash
cd ~/my_n8n./start.sh debug```
启动成功后，访问 http://localhost:5678
## 验证安装
### 检查 Node.js 版本
```bash
node --version # 应显示 v20.x.x```
### 验证 PostgreSQL 连接
```bash
# 查看数据库表
psql -U root -h localhost -d n8n -c "\dt"
# 查看工作流数量
psql -U root -h localhost -d n8n -c "SELECT COUNT(*) FROM workflow_entity;" 目录结构说明
bash
~/my_n8n/
├── .env # PostgreSQL 数据库配置
├── start.sh # 启动脚本（自动加载环境变量）
├── package.json # 项目配置和脚本
├── package-lock.json # 依赖版本锁定
└── node_modules/ # N8N 及其依赖 常见问题与解决方案
1. @oclif/core 错误
问题 : 启动时出现 ReferenceError: File is not defined 错误
原因: N8N v1.97.1 与 @oclif/core 在 Apple Silicon 上的兼容性问题
解决方案:
- 使用 Node.js 20 而不是 18
- 确保使用启动脚本
./start.sh来运行
2. 命令找不到错误
问题 : command start not found 或 n8n: command not found
原因: Node.js 版本不正确或 N8N 未正确安装
解决方案:
- 确保使用 Node.js 20：
nvm use 20 - 使用
npx n8n而不是直接运行n8n
3. PostgreSQL 连接失败
问题: 无法连接到 PostgreSQL 数据库
解决方案:
- 确认 PostgreSQL 正在运行：
brew services list - 确认数据库存在：
psql -U root -h localhost -l | grep n8n - 检查
.env文件中的数据库配置
4. 端口被占用
问题: Port 5678 is already in use
解决方案:
bash
# 查找占用端口的进程
lsof -i :5678
# 终止进程
kill -9 <PID> 5. npm 安装警告
问题 : 大量 npm warn EBADENGINE 警告
原因: 某些依赖包需要特定的 Node.js 版本
解决方案: 这些警告通常不影响 N8N 运行，可以忽略。确保使用 Node.js 20 可以减少警告。
6. 数据迁移
如果之前使用 SQLite，需要手动迁移数据：
- 从 SQLite 版本导出工作流
- 切换到 PostgreSQL 配置
- 导入工作流
维护建议
- 定期更新: 每月检查并更新 N8N 版本
- 数据备份: 定期备份 PostgreSQL 数据库
- 日志监控: 关注启动日志中的警告和错误
- 性能优化: PostgreSQL 比 SQLite 更适合生产环境使用
相关资源
本教程基于 N8N v1.106.3 和 Node.js v20.19.4 编写