外部钩子#

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

有两种类型：

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

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

后端钩子#

可用钩子#

钩子	参数	描述
`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]`	工作流执行前调用。可统计或限制工作流执行次数。
`workflow.update`	`[workflowData: IWorkflowBase]`	保存现有工作流前调用。
`workflow.afterArchive`	`[workflowId: string]`	归档工作流后调用。
`workflow.afterUnarchive`	`[workflowId: string]`	从归档恢复工作流后调用。

注册钩子#

Set hooks by registering a hook file that contains the hook functions. To register a hook, set the environment variable 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.'
                    );
                }
            }
        ]
    }
}

钩子函数#

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

如果钩子函数的参数是对象，则可以更改该参数的数据以更改 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 包中搜索钩子。