别让你的代码在角落吃灰
兄弟，代码写完了，工作流跑通了，然后呢？
笔者在 N8N大学 社区里，见过太多开发者把“轮子”造得飞快，却卡在了发布这一步。你辛辛苦苦开发的 n8n 自定义节点，如果只躺在你的本地硬盘里，那就太可惜了。它不仅无法复用，更失去了和全球开发者交流的机会。
今天，作为你的“引路人”，笔者就带你走通这临门一脚。我们将把你的节点发布到 npm 包管理器，并教你如何在本地 n8n 环境中通过 CLI 工具安装并测试它。走通这套流程，你就是 n8n 社区的贡献者。
准备工作：磨刀不误砍柴工
在出发前，我们需要确认你的“装备”是否齐全。别等到执行命令时报错才回头找依赖。
你需要具备以下硬性条件：
- Node.js 环境：确保你的电脑上安装了 Node.js (建议 v16 或更高版本)，并且 npm 命令可用。
- n8n 自定义节点项目：你已经完成了节点的开发，且项目结构符合 n8n 官方推荐的脚手架（通常是基于
n8n-node-starter模板）。 - 一个 npm 账号：如果你还没有，请先去 npmjs.com 注册一个。记住你的用户名和密码，或者提前配置好 Token（推荐后者，更安全）。
- 一个运行中的 n8n 实例：可以是本地安装的，也可以是 Docker 容器，只要能访问即可。
核心实操：从代码到 npm 包
这部分是重头戏。我们将分三步走，把你的“私有代码”变成“公共物资”。
步骤一：代码“体检”与配置修正
在发布前，必须检查 package.json 文件。这是 npm 识别你包的“身份证”。
重点关注以下字段：
name：包名必须是全局唯一的。建议采用n8n-nodes-的格式，例如n8n-nodes-my-cool-node。如果名字被占用了，npm 会报错。version：版本号。第一次发布建议写1.0.0。遵循语义化版本控制（Major.Minor.Patch）。main：指向编译后的入口文件，通常是dist/index.js。files：告诉 npm 哪些文件需要被打包上传。通常必须包含dist目录。
笔者提示：如果你的项目使用了 TypeScript，记得先运行 npm run build。很多新手忘了编译，上传上去的是一堆 .ts 源码，导致别人无法使用。
步骤二：登录 npm 与发布
打开你的终端（Terminal），进入你的项目根目录。
首先，检查你当前是否登录：
npm whoami如果提示未登录或报错，请执行：
npm login按照提示输入用户名、密码和邮箱。如果开启了双重验证（2FA），需要输入一次性密码。
确认登录成功后，执行发布命令：
npm publish如果一切顺利，你会看到一串绿色的“Success”字样。恭喜你，你的节点已经在全球 npm 仓库中“上市”了！
步骤三：在本地 n8n 中安装与测试
发布成功不代表万事大吉，我们得确保它真的能在 n8n 里跑起来。这步操作能让你在正式推送到 GitHub 前发现潜在 bug。
假设你的 n8n 是通过 Docker 或本地命令行运行的，你需要找到 n8n 的安装目录或容器环境。
方法 A：通过 CLI 安装（推荐）
如果你的 n8n 是全局安装的（npm install -g n8n），你可以直接在终端运行：
n8n install:nodes --npm n8n-nodes-这个命令会自动下载你的包并将其路径写入 n8n 的配置中。
方法 B：通过环境变量挂载（Docker 用户常用）
如果你是通过 Docker 运行 n8n，可以将 npm 包挂载到容器内部：
docker run -it --rm
--name n8n
-p 5678:5678
-v ~/.n8n:/home/node/.n8n
-e N8N_CUSTOM_EXTENSIONS="/home/node/.n8n/n8n-nodes-"
docker.n8n.io/n8nio/n8n避坑指南：安装完节点后，必须重启 n8n 服务（或者重启 Docker 容器）。否则，你在节点列表里是看不到新节点的。
避坑指南：那些年我们踩过的坑
发布过程看似简单，但笔者见过太多人在细节上翻车。以下是两个最高频的报错场景：
1. 401 Unauthorized / 403 Forbidden
npm ERR! 403 Forbidden - PUT https://registry.npmjs.org/...原因分析：通常是因为你没有登录，或者你试图发布一个与现有公共包重名的包（你没有权限覆盖别人的包）。如果你要发布私有包（Scoped package），比如 @yourname/n8n-nodes-xxx，你需要支付 npm 费用或者设置为私有。
2. 节点安装后不显示
原因分析：除了忘记重启 n8n，最常见的原因是 package.json 中的 n8n 字段配置错误。n8n 依靠这个字段来识别节点。请确保你的项目结构如下所示：
{
"name": "n8n-nodes-xxx",
"n8n": {
"n8nNodesApiVersion": 1,
"credentials": [],
"nodes": [
"dist/nodes/MyNode/MyNode.node.js"
]
}
}确保 dist 目录下的路径指向了真实的编译文件。
FAQ 问答
Q1: 我发布的节点是私有的，不想让别人搜到，怎么办？
A: 如果你不想开源，可以使用 Scoped 包名（例如 @yourname/n8n-nodes-xxx），并将 package.json 中的 private 属性设为 true。或者，你可以直接将代码托管在 GitHub 上，通过 Git 地址直接安装（例如 npm install git+https://github.com/your/repo.git），而无需发布到 npm。
Q2: 发布后我发现有 Bug，修改后怎么更新？
A: 只需要修改代码，然后在 package.json 中将 version 加 1（例如从 1.0.0 改为 1.0.1），再次运行 npm publish 即可。用户下次安装或更新时会自动拉取新版本。
Q3: 为什么我的节点在 n8n 编辑器界面显示为“Unknown”？
A: 这通常是节点类名（Class Name）与文件名不匹配导致的。检查你的代码中 export class MyNode ... 和 package.json 里定义的节点文件路径是否一致。同时也可能是编译后的 JS 文件缺少了默认导出。
总结与资源
将自定义节点发布到 npm，不仅是技术能力的证明，更是你参与开源社区的入场券。通过 CLI 工具在本地安装测试，能让你在公开发布前拥有足够的信心。
在 N8N大学，我们鼓励每一位开发者迈出这一步。如果你在发布过程中遇到任何报错，欢迎在社区留言，笔者会亲自为你排忧解难。
延伸阅读：
