n8n 中文文档

外部挂钩

外部钩子让你在 n8n 执行特定操作时运行自定义代码,可用于记录数据、修改数据,或通过抛出错误禁止某项操作。

有两种类型:

  • Backend hooks 后端钩子:在服务器端运行,通过 EXTERNAL_HOOK_FILES 环境变量注册。
  • Frontend hooks 前端钩子:在浏览器中运行,通过 script 标签加载。

用于注册hooks的环境变量请参考外部hooks环境变量。

后端挂钩

可用挂钩

钩子 参数 描述
credentials.create [credentialData: ICredentialsDb] 创建新凭据前调用。可用于限制凭据数量。
credentials.delete [id: credentialId] 删除凭据前调用。
credentials.update [credentialData: ICredentialsDb] n8n 保存现有凭据前调用。
frontend.settings [frontendSettings: IN8nUISettings] n8n 启动时调用。例如,可覆盖前端数据(如显示的 OAuth URL)。
n8n.ready [app: App] n8n 就绪后调用一次。例如,可注册自定义 API 端点。
n8n.stop n8n 进程停止时调用,可用于保存部分进程数据。
oauth1.authenticate [oAuthOptions: clientOAuth1.Options, oauthRequestData: {oauth_callback: string}] OAuth1 身份验证前调用,可用于覆盖 OAuth 回调 URL。
oauth2.callback [oAuth2Parameters: {clientId: string, clientSecret: string \| undefined, accessTokenUri: string, authorizationUri: string, redirectUri: string, scopes: string[]}] OAuth2 回调时调用,可用于覆盖 OAuth 回调 URL。
workflow.activate [workflowData: IWorkflowBase, workflowContext: WorkflowHookContextService, actor?: WorkflowLifecycleHookActor] 激活工作流前调用,可用于限制 active workflows 的数量。有关 workflowContext 参数,请参阅 Workflow hook context;有关 actor 参数,请参阅 Workflow lifecycle hook actor。
workflow.afterCreate [workflowData: IWorkflowBase, workflowContext: WorkflowHookContextService, actor?: WorkflowLifecycleHookActor] 创建工作流后调用。有关 workflowContext 参数,请参阅 Workflow hook context;有关 actor 参数,请参阅 Workflow lifecycle hook actor。
workflow.afterDelete [workflowId: string, actor?: WorkflowLifecycleHookActor] 删除工作流后调用。有关 actor 参数,请参阅 Workflow lifecycle hook actor。
workflow.afterUpdate [workflowData: IWorkflowBase, workflowContext: WorkflowHookContextService, actor?: WorkflowLifecycleHookActor] 保存现有工作流后调用。有关 workflowContext 参数,请参阅 Workflow hook context;有关 actor 参数,请参阅 Workflow lifecycle hook actor。
workflow.create [workflowData: IWorkflowBase, workflowContext: WorkflowHookContextService, actor?: WorkflowLifecycleHookActor] 创建工作流前调用,可用于限制已保存工作流的数量。有关 workflowContext 参数,请参阅 Workflow hook context;有关 actor 参数,请参阅 Workflow lifecycle hook actor。
workflow.deactivate [workflowData: IWorkflowBase, workflowContext: WorkflowHookContextService, actor?: WorkflowLifecycleHookActor] 停用工作流前调用,此时 active 仍为 true。抛出错误可中止停用并保持工作流处于 active 状态。自 n8n 2.33.1 起可用。有关 workflowContext 参数,请参阅 Workflow hook context;有关 actor 参数,请参阅 Workflow lifecycle hook actor。
workflow.delete [workflowId: string, actor?: WorkflowLifecycleHookActor] 删除工作流前调用。有关 actor 参数,请参阅 Workflow lifecycle hook actor。
workflow.postExecute [fullRunData: IRun \| undefined, workflowData: IWorkflowBase, executionId: string, workflowContext: WorkflowHookContextService] 工作流执行后调用。有关 workflowContext 参数,请参阅 Workflow hook context。
workflow.preExecute [workflow: Workflow, mode: WorkflowExecuteMode, workflowContext: WorkflowHookContextService] 工作流执行前调用,可用于统计或限制工作流执行次数。如果钩子抛出错误,n8n 不会创建执行记录。在 n8n 3.0.0 之前,可设置 N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTION=true,使钩子抛错时仍创建失败的执行;n8n 3.0.0 移除了该变量。有关 workflowContext 参数,请参阅 Workflow hook context(自 n8n 2.23.0 起可用)。
workflow.update [workflowData: IWorkflowBase, workflowContext: WorkflowHookContextService, actor?: WorkflowLifecycleHookActor] 保存现有工作流前调用。有关 workflowContext 参数,请参阅 Workflow hook context;有关 actor 参数,请参阅 Workflow lifecycle hook actor。
workflow.afterArchive [workflowId: string, actor?: WorkflowLifecycleHookActor] 归档工作流后调用。有关 actor 参数,请参阅 Workflow lifecycle hook actor。
workflow.afterUnarchive [workflowId: string, actor?: WorkflowLifecycleHookActor] 从归档中恢复工作流后调用。有关 actor 参数,请参阅 Workflow lifecycle hook actor。

注册钩子

通过注册包含钩子函数的钩子文件来设置钩子。要注册钩子,请设置 EXTERNAL_HOOK_FILES 环境变量。

您可以将变量设置为单个文件:

EXTERNAL_HOOK_FILES=/data/hook.js

或包含用冒号分隔的多个文件:

EXTERNAL_HOOK_FILES=/data/hook1.js:/data/hook2.js

挂钩文件

钩子文件是具有以下格式的常规 JavaScript 文件:

module.exports = {
    "frontend": {
        "settings": [
            async function (settings) {
                settings.oauthCallbackUrls.oauth1 = 'https://n8n.example.com/oauth1/callback';
                settings.oauthCallbackUrls.oauth2 = 'https://n8n.example.com/oauth2/callback';
            }
        ]
    },
    "workflow": {
        "activate": [
            async function (workflowData) {
                const activeWorkflows = await this.dbCollections.Workflow.count({ active: true });

                if (activeWorkflows > 1) {
                    throw new Error(
                        'Active workflow limit reached.'
                    );
                }
            }
        ]
    }
}

挂钩示例

如果缺少所需标签,则阻止工作流程执行

请注意:workflowContext 参数自 n8n 2.23.0 起提供给 workflow.preExecute hooks。有关接收该参数的完整 hooks 列表及其可用版本,请参阅 Workflow hook context。

使用 workflow.preExecute 在工作流缺少必需标签时中止执行:

module.exports = {
    workflow: {
        preExecute: [
            async function (workflow, mode, workflowContext) {
                const requiredTag = 'exampleTag';
                const workflowTags = await workflowContext.getWorkflowTags(workflow.id);
                if (!workflowTags.includes(requiredTag)) {
                    throw new Error(`Workflow is missing required tag "${requiredTag}", aborting`);
                }
            },
        ],
    },
};

Workflow hook context

部分 workflow hooks 会接收 workflowContext 参数,它是 WorkflowHookContextService 的实例。你可以在 hook function 中调用它暴露的 helper methods。

提示

自 n8n 2.23.0 起可用

n8n 会将 workflowContext 传递给 workflow.preExecute hook。

提示

自 n8n 2.33.1 起可用

n8n 会将 workflowContext 传递给 workflow.create、workflow.afterCreate、workflow.activate、workflow.deactivate、workflow.update、workflow.afterUpdate 和 workflow.postExecute hooks。

context 提供以下 methods:

Method Returns Description 描述
getWorkflowTags(workflowId: string) Promise<string[]> 返回指定 workflow 上附加的 tags 名称。
resolveIsTriggerNodeType(type: string, typeVersion?: number) boolean 如果给定 node type 是 trigger,则返回 true。type 是完整 node type 名称,例如 n8n-nodes-base.manualTrigger。typeVersion 默认为最新注册版本。当 n8n 无法解析 node type(例如实例上未注册该类型)时返回 false。

以下示例使用 resolveIsTriggerNodeType 阻止激活不包含 trigger node 的 workflow:

module.exports = {
    workflow: {
        activate: [
            async function (workflowData, workflowContext) {
                const hasTrigger = workflowData.nodes.some((node) =>
                    workflowContext.resolveIsTriggerNodeType(node.type, node.typeVersion),
                );
                if (!hasTrigger) {
                    throw new Error('Workflow must contain a trigger node, aborting activation');
                }
            },
        ],
    },
};

Workflow lifecycle hook actor

部分 workflow lifecycle hooks 会接收 actor 参数,它是执行该操作的用户的最小投影。可使用它标记 action 来源,例如根据用户 identity 或 role 允许或拒绝某个操作。

提示

自 n8n 2.33.1 起可用

n8n 会将 actor 传递给 workflow.create、workflow.afterCreate、workflow.activate、workflow.deactivate、workflow.update、workflow.afterUpdate、workflow.delete、workflow.afterDelete、workflow.afterArchive 和 workflow.afterUnarchive hooks。该参数是可选的;当 n8n 无法确定执行操作的用户时,可能为 undefined。

actor object 包含以下 properties:

Property Type Description 描述
id string 用户的唯一 ID。
email string \| null 用户 email address。可以为 null,例如用户已被邀请但尚未完成设置时。
firstName string \| null 用户名。可以为 null,例如用户已被邀请但尚未完成设置时。
lastName string \| null 用户姓氏。可以为 null,例如用户已被邀请但尚未完成设置时。
role string 用户 role slug,例如 global:admin。可选。

以下示例使用 actor 记录是谁删除了 workflow:

module.exports = {
    workflow: {
        delete: [
            async function (workflowId, actor) {
                console.log(`Workflow ${workflowId} deleted by ${actor?.email} (${actor?.role})`);
            },
        ],
    },
};

钩子函数

一个钩子或钩子文件可以包含多个钩子函数,所有函数依次执行。

如果钩子函数的参数是对象,则可以更改该参数的数据以更改 n8n 的行为。

你也可以在任何钩子函数中通过 this.dbCollections 访问数据库(参见上文 钩子文件 中的代码示例)。

前端外部挂钩

与后端外部钩子一样,可以在前端代码中定义外部钩子,当用户执行特定操作时由 n8n 执行。您可以使用它们,例如,记录数据和更改数据。

可用挂钩

钩子 描述
credentialsEdit.credentialTypeChanged 现有凭据类型变更时调用。
credentials.create 有人创建新凭据时调用。
credentialsList.dialogVisibleChanged
dataDisplay.nodeTypeChanged
dataDisplay.onDocumentationUrlClick 有人点击帮助文档链接时调用。
execution.open 打开现有执行时调用。
executionsList.openDialog 有人从「工作流执行」列表中选择某次执行时调用。
expressionEdit.itemSelected
expressionEdit.dialogVisibleChanged
nodeCreateList.filteredNodeTypesComputed
nodeCreateList.nodeFilterChanged 有人更改节点面板筛选条件时调用。
nodeCreateList.selectedTypeChanged
nodeCreateList.mounted
nodeCreateList.destroyed
nodeSettings.credentialSelected
nodeSettings.valueChanged
nodeView.createNodeActiveChanged
nodeView.addNodeButton
nodeView.mount
pushConnection.executionFinished
showMessage.showError
runData.displayModeChanged
workflow.activeChange
workflow.activeChangeCurrent
workflow.afterUpdate 有人更新现有工作流时调用。
workflow.open
workflowRun.runError
workflowRun.runWorkflow 工作流执行时调用。
workflowSettings.dialogVisibleChanged
workflowSettings.saveSettings 有人保存工作流设置时调用。

注册前端钩子

您可以通过在页面上加载钩子脚本来设置钩子。一种方法是在项目中创建钩子文件并在您的 editor-ui/public/index.html 文件中添加脚本标签:

<script src="frontend-hooks.js"></script>

前端挂钩文件

前端外部钩子文件是具有以下格式的常规 JavaScript 文件:

window.n8nExternalHooks = {
  nodeView: {
    mount: [
      function (store, meta) {
        // 做某事
      },
    ],
    createNodeActiveChanged: [
      function (store, meta) {
        // 做某事
      },
      function (store, meta) {
        // 做其他事
      },
    ],
    addNodeButton: [
      function (store, meta) {
        // 做某事
      },
    ],
  },
};

前端钩子函数

每个钩子可定义多个钩子函数。n8n 使用以下参数调用每个钩子函数:

  • store:Vuex 存储对象。您可以使用它来更改或从存储中获取数据。
  • metadata:包含钩子提供的任何数据的对象。要查看传递的内容,请在 editor-ui 包中搜索钩子。

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。