Astro Actions服务端动作返回类型如何在TypeScript中正确定义？

Astro从4.0开始引入的Actions机制让前后端数据交互变得非常简洁，但TypeScript用户很快会发现一个问题：客户端通过astro:actions调用动作时，返回值的类型经常被推断为any，或者推断结果与服务端实际返回的结构对不上。这并不是Astro的设计缺陷，而是类型定义的写法没有被正确使用。本文将围绕类型定义这一核心，从动作定义、输入校验、错误处理到跨文件复用，完整讲清楚如何在TypeScript中把服务端动作的返回类型管起来。

一、为什么返回类型会丢失：理解defineAction的类型机制

先看一个最常见的错误写法。很多开发者习惯性地在服务端动作里给返回值手动标注类型，然后期望客户端能自动拿到这个类型：

import { defineAction } from 'astro:actions';
import { z } from 'astro:schema';

export const getUser = defineAction({
  input: z.object({
    id: z.number()
  }),
  handler: async (input): Promise<{ name: string; age: number }> => {
    // 手动标注了返回类型
    return { name: '张三', age: 25 };
  }
});

这个写法本身不会报错，问题出在客户端调用时。如果你在组件或脚本里写import { actions } from 'astro:actions'然后调用actions.getUser()，返回类型可能不是你期望的结构。原因在于Astro对Actions的类型推导依赖虚拟模块astro:actions的声明文件生成，这个过程会扫描src/actions目录下的所有defineAction调用，并提取handler的返回类型。如果你使用了astro sync之前没有重新执行，或者TypeScript的Language Server缓存过期，类型就会滞留在旧状态。

遇到类型变成any的情况，第一步应该做的是执行npx astro sync。这个命令会重新生成.astro/types.d.ts，其中包含了Actions的类型声明。很多人折腾半天类型定义，最后发现只是忘了sync，这一点值得优先排查。

第二个常见原因是把动作直接定义在.astro文件内部或者非约定目录中。Astro只有对src/actions/index.ts以及它引用的模块才会生成类型。如果你的动作分散在各个页面文件里，客户端的astro:actions虚拟模块自然找不到对应的类型信息。

二、正确的类型定义方式：让handler的返回类型自然流动

Astro官方推荐的做法是不要过度手动标注，让TypeScript自己从handler的实现推导返回类型，然后由Astro把这个类型传递给客户端调用处。推荐的目录结构如下：

src/
  actions/
    index.ts
    user.ts
    post.ts

在src/actions/index.ts中统一导出所有分组：

import { actions } from './user';
import { actions as postActions } from './post';

export const server = {
  user: actions,
  post: postActions
};

在src/actions/user.ts中定义具体的动作。注意这里handler的返回值没有手动标注类型，TypeScript会根据return语句自动推导：

import { defineAction } from 'astro:actions';
import { z } from 'astro:schema';

export const actions = {
  getProfile: defineAction({
    input: z.object({
      userId: z.string().min(1)
    }),
    handler: async ({ userId }) => {
      // 数据库查询，这里用模拟数据代替
      const record = { userId, name: '李四', vip: true, tags: ['pro', 'beta'] };
      // 返回类型自动推导为 { userId: string; name: string; vip: boolean; tags: string[] }
      return record;
    }
  }),

  updateProfile: defineAction({
    input: z.object({
      userId: z.string(),
      name: z.string().max(30)
    }),
    handler: async ({ userId, name }, context) => {
      const ok = await db.update(userId, { name });
      if (!ok) {
        throw new ActionError({
          code: 'INTERNAL_SERVER_ERROR',
          message: '更新失败'
        });
      }
      return { success: true };
    }
  })
};

这种写法的关键在于：返回类型完全由实现侧的return语句决定，客户端调用actions.user.getProfile({ userId: 'u1' })时，编辑器能直接提示出name、vip、tags这些字段。输入侧的类型则由zod schema推导，参数传错类型或缺少必填字段时，在编写阶段就会报红。

需要导入ActionError时，记得从astro:actions导入，而不是自己定义一个错误类。Astro对抛出的ActionError有专门的类型通道，客户端拿到的是被包装后的错误对象，包含code和message字段，这在下一节会详细展开。

三、错误分支与类型收窄：不要让any污染调用链

Actions的返回结果分为两种形态：直接调用（如actions.xxx.orThrow()）和通过astro:actions/client的安全调用。安全调用返回的结果是一个包含data与error的联合类型，处理时必须做类型收窄，否则data会被推断为可能为undefined，直接访问字段会报错。

import { actions } from 'astro:actions/client';

const result = await actions.user.getProfile({ userId: 'u1' });

if (result.error) {
  // 收窄后 error 是 ActionError，code 和 message 都有完整类型
  console.error(result.error.code, result.error.message);
} else {
  // 这里 result.data 的类型就是服务端返回的结构，无需断言
  console.log(result.data.name, result.data.vip);
}

一个典型的反面教材是用as any或者可选链硬绕过类型检查，比如result.data?.name配上@ts-ignore。这种写法短期省事，但一旦服务端返回结构变化，客户端不会有任何编译期警告，问题会一直拖到运行时才暴露。正确的思路是始终用if (result.error)分支判断，让TypeScript自动完成联合类型的收窄。

还有一种情况是handler内部逻辑复杂，返回结构在多个分支中不同。此时建议先定义一个明确的返回类型别名，再统一标注，避免不同分支推导出细微不一致的类型（比如一个分支返回string，另一个返回string | null）导致客户端拿到过宽的联合类型：

export type UpdateResult = {
  success: boolean;
  affectedRows?: number;
};

export const actions = {
  updateProfile: defineAction({
    input: z.object({ userId: z.string() }),
    handler: async ({ userId }): Promise<UpdateResult> => {
      const affected = await db.update(userId, {});
      if (affected === 0) return { success: false };
      return { success: true, affectedRows: affected };
    }
  })
};

注意这里手动标注Promise<UpdateResult>是合理的，因为统一标注能压制各分支的推导差异，而且UpdateResult可以在客户端复用，用来标注组件内部的本地变量或状态管理的state类型。

四、跨文件复用类型：导出与共享的注意事项

当项目规模变大，前端组件经常需要引用动作的返回类型。直接导出类型别名是最简单的方式，但还有更省事的办法：利用Astro提供的InferInput与InferOutput工具类型，从动作本身反查类型，这样即使handler返回结构调整，引用处也无需改动：

import type { InferInput, InferOutput } from 'astro:actions';
import { actions } from '@/actions/user';

// 从动作定义直接提取类型
type ProfileInput = InferInput<typeof actions.getProfile>;
type ProfileOutput = InferOutput<typeof actions.getProfile>;

async function loadProfile(input: ProfileInput): Promise<ProfileOutput> {
  const result = await actions.getProfile(input);
  if (result.error) throw result.error;
  return result.data;
}

这里有两点容易踩坑。第一，类型导入必须用import type，混入普通导入会导致构建时报astro:actions模块被客户端bundle引用的错误。第二，如果你的路径别名使用了@/，确认tsconfig.json中的paths配置覆盖到了src/actions目录，否则类型解析会失败，编辑器会给出无法找到模块的提示。

另外，把动作封装成公共库或者monorepo共享包时，要确保包的package.json中声明了exports字段并正确导出类型文件，同时Astro版本保持一致。Actions的类型生成机制与Astro核心版本绑定，跨版本引用可能出现类型结构不兼容的情况，升级Astro后记得重新执行astro sync并检查.astro目录下生成的声明文件是否有变化。

总结一下核心原则：让返回类型从handler的实现自然流出，输入类型交给zod schema，复杂返回结构用统一的类型别名标注，客户端通过InferOutput复用类型，错误处理一律走result.error分支收窄。掌握这套思路后，Astro Actions在TypeScript项目中就能获得与本地函数调用几乎一致的类型体验。

Astro ActionsTypeScript类型定义服务端动作修改时间：2026-09-04 05:06:45