🛠️ 实战教程：打造支持视频下载的 n8n 本地“刚很多”环境#

📂 目录结构一览#

为了不仅让程序跑起来，还要方便管理，我们采用了 “配置与数据分离” 的结构。开始动手前，请确保你的目录看起来像这样：

📁 n8n-self/                <-- 【项目目录】放配置代码 (本教程就在这操作)
├── 📄 Dockerfile           # 镜像构建文件
└── 📄 docker-compose.yml   # 容器启动文件

📁 ~/Documents/n8n/         <-- 【数据目录】放运行数据 (自动同步到 Mac)
├── 📂 downloads/           # 📥 下载的文件直接出现在这！
└── 📄 ...                  # ⚙️ n8n 的数据库和工作流数据

第一步：改装镜像 (Dockerfile)#

官方镜像太精简了，我们需要在此基础上“加料”。在项目根目录创建一个 Dockerfile：

这里有几个关键点别写错了：

• 切换 root：默认是 node 用户，没权限装软件，所以开头必须切 root。
• break-system-packages：最近 pip 加上了保护机制，不加这行装不上 yt-dlp。
• 最后切回 node：装完软件记得切回普通用户，安全第一。

# 基于官方最新镜像
FROM docker.n8n.io/n8nio/n8n:1

# 必须切换到 root 才有权限装软件
USER root

# (可选) 如果构建很慢，可以把下面这行注释打开换成阿里源
# RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories

# 1. 安装核心工具：ffmpeg(处理视频), python3(运行yt-dlp), nodejs
# 注意：显式安装 nodejs 是为了防止某些工具找不到 /usr/bin/node 路径
RUN apk update && apk add --no-cache ffmpeg python3 py3-pip nodejs

# 2. 安装下载神器 yt-dlp
# --break-system-packages 是必须的，否则新版系统会报错阻止安装
RUN pip3 install --break-system-packages yt-dlp

# 3. 验证一下装没装上 (构建失败比运行失败好排查)
RUN node -v && yt-dlp --version

# 切回普通用户启动服务
USER node

第二步：编排容器 (docker-compose.yml)#

我们要用 docker-compose 来管理这个容器，主要是为了解决路径映射的问题。

在同级目录创建 docker-compose.yml：

重点看 volumes 部分，这直接决定了你用得爽不爽：

• .n8n 映射：把 n8n 的数据库和配置保存在你的 Documents 下。
• downloads 映射：这个最重要。你在 n8n 里把文件下载到 /home/node/downloads，它就会魔术般地出现在你 Mac 的 /Users/edy/Documents/n8n/downloads 里。

version: '3.8'

services:
  n8n:
    # 告诉 compose 用当目录下的 Dockerfile 现场构建，而不要去拉官方的
    build: .
    container_name: n8n
    restart: always
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=localhost
      - N8N_PORT=5678
      - N8N_PROTOCOL=http
      - NODE_ENV=production
      - WEBHOOK_URL=http://localhost:5678/
      # 设成上海时间，不然你看日志全是只有上帝知道的 UTC 时间
      - GENERIC_TIMEZONE=Asia/Shanghai
      - TZ=Asia/Shanghai
    volumes:
      # 1. 数据持久化：工作流、凭证都在这，删了容器也不怕
      - /Users/[name]/Documents/n8n:/home/node/.n8n

      # 2. 媒体通道：容器里下载好的东西，直接投送到你 Mac 文件夹
      - /Users/[name]/Documents/n8n/downloads:/home/node/downloads

第三步：启动与验证#

打开终端，在当前目录下运行一句话命令：

docker-compose up -d --build

• --build：确保它确实使用了你的 Dockerfile 重新构建，而不是用旧缓存。

怎么算成功？

1. 打开浏览器访问 http://localhost:5678，看 n8n 能不能出来。
2. 新建一个 n8n 工作流，弄个 “Execute Command” 节点，输入 yt-dlp --version。如果输出版本号，恭喜你，你的 n8n 已经进化了。

搞定！现在你可以去折腾那些自动下载 YouTube 视频并转码发到通知栏的高级玩法了。

💡 避坑指南：yt-dlp 命令行的玄学配置#

如果你在 n8n 的 Execute Command 节点中运行 yt-dlp 时频频报错，建议直接抄作业使用以下命令参数。这些都是“血的教训”换来的经验：

yt-dlp --js-runtimes "node:/usr/local/bin/node" \
  --remote-components ejs:github \
  -f "best[ext=mp4]/best" \
  --cookies {{ $('Setup Variables').item.json.cookies }} \
  --merge-output-format mp4 \
  -o "{{ $('Setup Variables').item.json.work_dir }}/{{ $('Setup Variables').item.json.video_filename }}" \
  "{{ $('Setup Variables').item.json.youtube_url }}"