Skip to content

外部钩子(External hooks)#

外部钩子让你在 n8n 执行特定操作时运行自定义代码。使用它们来记录数据、更改数据，或通过抛出错误来禁止某个操作。

🌐 External hooks let you run custom code whenever n8n performs a specific operation. Use them to log data, change data, or forbid an action by throwing an error.

有两种类型：

🌐 There are two types:

  • 后端钩子：在服务器端运行，通过 EXTERNAL_HOOK_FILES 环境变量注册。
  • 前端钩子：在浏览器中运行，通过脚本标签加载。

有关用于注册钩子的环境变量，请参阅 外部钩子环境变量。

🌐 For the environment variables used to register hooks, refer to External hooks environment variables.

后端钩子(Backend hooks)#

可用钩子(Available 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: IWorkflowDb] 在工作流激活之前调用。用于限制活动工作流的数量。
workflow.afterCreate [workflowId: string] 在工作流创建后调用。
workflow.afterDelete [workflowId: string] 在工作流被删除后调用。
workflow.afterUpdate [workflowData: IWorkflowBase] 在现有工作流保存后调用。
workflow.create [workflowData: IWorkflowBase] 在创建工作流之前调用。用于限制已保存工作流的数量。
workflow.delete [workflowId: string] 在工作流被删除之前调用。
workflow.postExecute [run: IRun, workflowData: IWorkflowBase] 在工作流执行后调用。
workflow.preExecute [workflow: Workflow, mode: WorkflowExecuteMode, workflowContext: WorkflowHookContextService] 在工作流执行之前调用。允许你统计或限制工作流的执行次数。有关使用 workflowContext 参数的示例，请参阅 Hook 示例（仅从版本 2.23.0 起可用）。
workflow.update [workflowData: IWorkflowBase] 在现有工作流被保存之前调用。
workflow.afterArchive [workflowId: string] 在你归档工作流后调用。
workflow.afterUnarchive [workflowId: string] 在你从归档恢复工作流后调用。

正在注册钩子(Registering hooks)#

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

🌐 Set hooks by registering a hook file that contains the hook functions. To register a hook, set the environment variable EXTERNAL_HOOK_FILES.

你可以将变量设置为单个文件：

🌐 You can set the variable to a single file:

EXTERNAL_HOOK_FILES=/data/hook.js

或者，包含多个以冒号分隔的文件：

🌐 Or to contain multiple files separated by a colon:

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

钩子文件(Hook files)#

钩子文件是常规的 JavaScript 文件，格式如下：

🌐 Hook files are regular JavaScript files that have the following format:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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.'
                    );
                }
            }
        ]
    }
}

钩子示例(Hook examples)#

如果缺少必需的标签，则阻止工作流执行(Block workflow execution if a required tag is missing)#

请注意：workflowContext 参数仅从 n8n 版本 2.23.0 开始提供给 workflow.preExecute 钩子。

🌐 Please note: the workflowContext argument is only supplied to workflow.preExecute hooks from n8n version 2.23.0.

当工作流没有必需的标签时，使用 workflow.preExecute 中止执行：

🌐 Use workflow.preExecute to abort execution when a workflow doesn't have a required tag:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
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`);
				}
			},
		],
	},
};

钩子函数(Hook functions)#

钩子或钩子文件可以包含多个钩子函数，所有函数按顺序执行。

🌐 A hook or a hook file can contain multiple hook functions, with all functions executed one after another.

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

🌐 If the parameters of the hook function are objects, it's possible to change the data of that parameter to change the behavior of n8n.

你也可以在任何钩子函数中使用 this.dbCollections 访问数据库（参考上面 Hook files 中的代码示例）。

🌐 You can also access the database in any hook function using this.dbCollections (refer to the code sample in Hook files above).

前端外部钩子(Frontend external hooks)#

就像后端的外部钩子一样，也可以在前端代码中定义外部钩子，每当用户执行特定操作时，n8n 都会执行这些钩子。例如，你可以使用它们来记录数据和修改数据。

🌐 Like backend external hooks, it's possible to define external hooks in the frontend code that get executed by n8n whenever a user performs a specific operation. You can use them, for example, to log data and change data.

可用钩子(Available hooks)#

钩子 描述
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 当有人保存工作流设置时调用。

注册前端钩子(Registering frontend hooks)#

你可以通过在页面上加载 hooks 脚本来设置 hooks。其中一种方法是在项目中创建一个 hooks 文件，并在你的 editor-ui/public/index.html 文件中添加一个 script 标签：

🌐 You can set hooks by loading the hooks script on the page. One way to do this is by creating a hooks file in the project and adding a script tag in your editor-ui/public/index.html file:

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

前端钩子文件(Frontend hook files)#

前端外部钩子文件是常规的 JavaScript 文件，格式如下：

🌐 Frontend external hook files are regular JavaScript files which have the following format:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
window.n8nExternalHooks = {
  nodeView: {
    mount: [
      function (store, meta) {
        // do something
      },
    ],
    createNodeActiveChanged: [
      function (store, meta) {
        // do something
      },
      function (store, meta) {
        // do something else
      },
    ],
    addNodeButton: [
      function (store, meta) {
        // do something
      },
    ],
  },
};

前端钩子函数(Frontend hook functions)#

你可以为每个钩子定义多个钩子函数。n8n 会使用以下参数调用每个钩子函数：

🌐 You can define multiple hook functions per hook. n8n calls each hook function with the following arguments:

  • store：Vuex 存储对象。你可以用它来更改或获取存储中的数据。
  • metadata：包含钩子提供的任何数据的对象。要查看传递了什么，请在 editor-ui 包中搜索该钩子。