---
order: 6
navTitle: 程序流脚本节点
---
# 后端程序流脚本节点

后端程序流脚本节点运行在服务器端，用于在程序流中调用 `.action.ts` 或 `hooks.action.ts` 中的自定义脚本函数。它适合处理内置节点不方便表达的服务端业务逻辑，例如复杂校验、访问数据库、调用服务端 API、读写文件，或把一段可复用逻辑封装成程序流节点。

如果脚本只处理浏览器页面内的组件状态、用户事件或页面上下文，优先使用[前端程序流脚本节点](../frontend/action-flow-script-node.md)。

## 写在哪里{#where}

按复用范围选择脚本位置：只给一个资源使用，写在资源同目录的同名 `.action.ts`；应用或项目内多个资源复用，写到对应层级的 `hooks.action.ts`；多个项目复用时，再考虑系统级脚本。具体路径和作用范围见[脚本文件组织](../file-organization.md#backend-script)。

## 编写脚本函数{#usage}

后端程序流脚本函数使用 `action_` 作为函数名前缀。系统会从脚本中识别 `action_` 开头的函数，并在程序流**执行后端脚本**节点的函数选择项中列出。

```ts
export function action_buildAuditMessage(
  args: { orderNo: string; amount: number },
  ctx: any
): string {
  if (!args.orderNo) {
    throw new Error('订单号不能为空');
  }

  const level = args.amount >= 100000 ? '大额订单' : '普通订单';
  return `${level}：${args.orderNo}`;
}
```

写法要求：

1. 函数名以 `action_` 开头。
2. 建议使用 `export` 导出函数，便于设计器解析函数并在节点配置中选择。
3. 第一个参数使用对象接收节点参数，属性名和节点上配置的参数名一致。
4. 第二个参数是程序流节点运行上下文。需要使用上下文能力时，先查看当前版本的类型声明。
5. 函数返回值会作为当前脚本节点的执行结果，可在后续节点中通过该节点的 `$result` 输出变量继续使用。

## 配置节点{#configure}

在程序流设计器中添加**执行后端脚本**节点后，按下面方式配置：

1. 选择脚本文件，例如页面同名 `.action.ts`、应用级 `hooks.action.ts` 或项目级 `hooks.action.ts`。
2. 选择执行函数。节点会从脚本文件中列出 `action_` 开头的函数。
3. 设置参数。参数值可以写常量，也可以写表达式引用程序流参数、模型字段或前序节点结果。
4. 设置输出变量。需要给后续节点使用返回值时，在节点输出变量中保存 `$result`。

如果直接编辑元数据，`executeActionScript.method` 按后端脚本导出的函数名填写，例如 `action_buildAuditMessage`。

例如节点参数配置为：

| 参数名 | 参数值 |
| :--- | :--- |
| `orderNo` | `params.orderNo` |
| `amount` | `[订单].[金额]` |

脚本函数会收到：

```ts
{
  orderNo: 'SO-20260628-001',
  amount: 128000
}
```

参数名应保持稳定。已经被程序流节点引用的参数，不要随意改名；确需调整时，同步修改节点参数配置和后续引用。

## 返回值和异常{#result-error}

脚本函数可以返回字符串、数值、布尔值、对象或数组。返回值会进入当前脚本节点的 `$result`，后续节点可以用表达式读取。

```ts
export function action_createResult(args: { success: boolean; message: string }, ctx: any) {
  return {
    success: args.success,
    message: args.message,
    time: new Date()
  };
}
```

如果函数没有返回值，`$result` 为空。需要让后续分支根据执行结果判断时，建议显式返回状态对象，而不是只依赖异常。

```ts
export function action_validateAmount(args: { amount: number }, ctx: any) {
  if (args.amount == null || args.amount <= 0) {
    return { success: false, message: '金额必须大于 0' };
  }
  return { success: true };
}
```

脚本函数中抛出的异常会导致脚本节点执行失败。需要给用户明确提示时，在错误信息中写清可处理原因，例如缺少参数、权限不足、外部接口不可用等。

## 事务和权限{#transaction-permission}

后端脚本节点在服务器端执行，适合处理需要可信执行的业务逻辑。读取或修改数据时，应优先使用后端脚本 API，并让程序流统一控制权限、错误分支和提交结果。

如果脚本通过程序流上下文取得连接对象，不要在脚本中自行提交事务；程序流会在流程结束时统一处理提交或回滚。确实需要脱离程序流事务时，应使用独立连接并自行控制提交、关闭和异常处理。

## 相关类型{#types}

需要核对字段或运行环境时，可查看以下类型声明：

- 程序流执行脚本概念：[`types/internal/succ.concepts.d.ts`](../../../../dev-types/types/internal/succ.concepts.d.ts)
- 执行后端脚本节点元数据：[`types/meta/actionComponent/executeActionScript.d.ts`](../../../../dev-types/types/meta/actionComponent/executeActionScript.d.ts)
- 后端程序流脚本类型：[`svr-api/types/actionflow.types.d.ts`](../../../../dev-types/svr-api/types/actionflow.types.d.ts)

更多程序流节点结构见 [.afl 程序流元数据](../../meta/file-types/backend/afl.md)。