Next.js 15 中 Next-safe-action 库的异步函数要求解析

问题背景

在 Next.js 15 版本中，开发者在使用 next-safe-action 库时遇到了一个特殊问题：当在服务器端动作(Server Actions)中使用 handleValidationErrorsShape 函数时，系统会强制要求该函数必须声明为异步(async)函数。这个问题不仅影响了 next-safe-action 库，也影响了其他类似的服务器动作库。

技术细节分析

Next.js 15 对服务器端动作的处理机制进行了调整，现在要求所有通过 "use server" 指令导出的顶层函数都必须是异步函数。这一变化影响了函数链式调用模式中的每个回调函数。

具体表现为：

1. 在 "use server" 文件中，任何被导出的函数都必须标记为 async
2. 函数链式调用中，每个链式方法调用的回调函数也需要是 async 函数
3. 非导出的辅助函数则不受此限制

解决方案

针对这一变化，开发者可以采取以下解决方案：

1. 添加 async 关键字：在所有被 Next.js 识别为"顶层"的函数前添加 async 关键字，即使这些函数实际上并不需要异步执行。

2. 避免导出非动作函数：不要导出那些不需要作为服务器动作使用的辅助函数和客户端。

3. 等待官方修复：Next.js 团队已经确认这是有意为之的行为变更，未来可能会提供更灵活的解决方案。

实际应用示例

假设我们有一个简单的联系表单处理动作：

"use server";
import { createSafeActionClient } from "next-safe-action";

// 注意这里移除了 export，因为这不是一个动作函数
const actionClient = createSafeActionClient();

export const contactAction = actionClient
  .schema(/* 验证模式 */)
  .action(async ({ parsedInput }) => {
    // 处理逻辑
    return { success: true };
  });

对开发体验的影响

这一变更虽然增加了开发时的约束，但也带来了一些好处：

1. 更明确的异步意图：强制 async 标记使代码的异步性质更加明显
2. 统一的代码风格：所有服务器动作都遵循相同的模式
3. 减少潜在错误：避免了同步函数意外阻塞事件循环的情况

最佳实践建议

1. 为所有服务器动作函数添加 async 关键字，即使它们不包含 await 操作
2. 将非动作的辅助函数和客户端声明为非导出，或移动到单独的文件中
3. 在团队中建立统一的代码风格指南，处理这类情况
4. 关注 Next.js 官方更新，了解这一限制的未来发展

总结

Next.js 15 对服务器动作的异步要求虽然带来了一些适配成本，但从长远来看有助于建立更健壮的服务器端代码结构。next-safe-action 库的用户需要相应调整代码风格，但核心功能不受影响。随着社区对这一变化的适应，相关的开发模式和最佳实践也将逐步成熟。