# npm
npm install ky
 
# pnpm
pnpm add ky
 
# yarn
yarn add ky
 
# bun
bun add ky

import ky from 'ky';
 
// 最简单的 GET 请求
const json = await ky('https://api.example.com/users/1').json();
 
// 使用快捷方法
const user = await ky.get('https://api.example.com/users/1').json();
 
// POST 请求，自动 JSON 序列化
const result = await ky.post('https://api.example.com/users', {
  json: { name: 'Alice', email: '[email protected]' }
}).json();

import ky from 'ky';
 
// 创建带默认配置的实例
const api = ky.create({
  prefix: 'https://api.example.com',
  timeout: 10000,
  retry: { limit: 3 },
  hooks: {
    beforeRequest: [
      (request) => {
        request.headers.set('Authorization', `Bearer ${getToken()}`);
      }
    ],
    afterResponse: [
      async ({ response }) => {
        if (!response.ok) {
          console.error(`请求失败: ${response.status}`);
        }
      }
    ]
  }
});
 
// 使用实例发请求（自动携带 prefix、auth、timeout 等）
const users = await api.get('users').json();
const newUser = await api.post('users', { json: { name: 'Bob' } }).json();

const baseApi = ky.create({ prefix: 'https://api.example.com' });
 
// 基于基础实例扩展，继承所有配置
const usersApi = baseApi.extend({
  prefix: 'https://api.example.com/users'
});
 
// 也可以继承并覆盖部分配置
const adminApi = baseApi.extend({
  hooks: {
    beforeRequest: [
      (request) => {
        request.headers.set('X-Admin', 'true');
      }
    ]
  }
});

const json = await ky.get('https://api.example.com/data', {
  retry: {
    limit: 5,
    methods: ['get', 'post'],
    statusCodes: [408, 413, 429, 500, 502, 503, 504],
    // 自定义延迟函数
    delay: (attemptCount) => 0.3 * (2 ** (attemptCount - 1)) * 1000,
    // 添加抖动防止惊群效应
    jitter: true,
    // 自定义重试判断
    shouldRetry: ({ error, retryCount }) => {
      if (error instanceof HTTPError && error.response.status === 429) {
        return retryCount <= 3;
      }
      return undefined; // 使用默认逻辑
    }
  }
}).json();

const data = await ky.get('/api/slow-endpoint', {
  timeout: 5000,        // 单次请求超时 5s
  totalTimeout: 30000   // 总超时（含重试）30s
}).json();

const api = ky.create({
  hooks: {
    // 请求构建前（同步）
    init: [
      (options) => {
        options.searchParams = { apiKey: getApiKey() };
      }
    ],
    // 请求发送前
    beforeRequest: [
      ({ request }) => {
        request.headers.set('Authorization', `Bearer ${token}`);
      }
    ],
    // 重试前（可刷新 token）
    beforeRetry: [
      async ({ request, retryCount }) => {
        const newToken = await refreshToken();
        request.headers.set('Authorization', `Bearer ${newToken}`);
      }
    ],
    // 响应后（可触发重试）
    afterResponse: [
      async ({ response, request }) => {
        if (response.status === 429) {
          return ky.retry({ delay: 5000 });
        }
      }
    ],
    // 错误抛出前（可修改错误）
    beforeError: [
      ({ error, request }) => {
        if (isHTTPError(error)) {
          error.message = `API 错误: ${error.response.status}`;
        }
        return error;
      }
    ]
  }
});

import { z } from 'zod';
import ky, { SchemaValidationError } from 'ky';
 
const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email()
});
 
try {
  const user = await ky.get('/api/user/1').json(UserSchema);
  // user 类型自动推导为 { id: number; name: string; email: string }
  console.log(user.name);
} catch (error) {
  if (error instanceof SchemaValidationError) {
    console.error('数据校验失败:', error.issues);
  }
}

// 下载进度
const response = await ky.get('https://example.com/large-file', {
  onDownloadProgress: ({ percent, transferredBytes, totalBytes }) => {
    console.log(`下载进度: ${(percent * 100).toFixed(1)}%`);
  }
});
 
// 上传进度
await ky.post('https://example.com/upload', {
  body: formData,
  onUploadProgress: ({ percent }) => {
    console.log(`上传进度: ${(percent * 100).toFixed(1)}%`);
  }
});

import ky, { isHTTPError, isNetworkError, isTimeoutError } from 'ky';
 
try {
  const data = await ky.get('/api/data').json();
} catch (error) {
  if (isHTTPError(error)) {
    console.error(`HTTP 错误: ${error.response.status}`, error.data);
  } else if (isTimeoutError(error)) {
    console.error('请求超时');
  } else if (isNetworkError(error)) {
    console.error('网络错误:', error.cause);
  }
}

ky.get(url, options)
ky.post(url, options)
ky.put(url, options)
ky.delete(url, options)
ky.patch(url, options)
ky.head(url, options)

import ky, { replaceOption } from 'ky';
 
const base = ky.create({
  hooks: { beforeRequest: [addAuth, addTracking] }
});
 
// 替换而非追加
const clean = base.extend({
  hooks: replaceOption({ beforeRequest: [onlyThisHook] })
});
// clean 的 beforeRequest 现在只有 [onlyThisHook]

// 浏览器、Node.js 22+、Bun、Deno 均可直接运行
import ky from 'ky';
 
// 无需 polyfill，无需条件导入
const data = await ky('https://api.example.com').json();

// 请求体自动 JSON 序列化
await ky.post('/users', { json: { name: 'Alice' } });
 
// 响应体自动 JSON 解析
const user = await ky.get('/users/1').json();
 
// v2.0: 空响应和 204 响应会抛出错误（不再静默返回空字符串）

interface User {
  id: number;
  name: string;
  email: string;
}
 
// 使用 Standard Schema 推导类型
const user = await ky.get('/user/1').json(UserSchema);
// user: { id: number; name: string; email: string }
 
// 泛型方式（不推荐，v2.0 推荐用 Schema）
const data = await ky.get('/users').json<User[]>();

// 方式一：使用动态 import（Node.js）
const { default: ky } = await import('ky');
 
// 方式二：使用 CJS 兼容分支
// npm install @smeijer/ky
import ky from '@smeijer/ky';
 
// 方式三：在 package.json 中设置 "type": "module"

// Vitest 测试示例
import { describe, it, expect, vi } from 'vitest';
import ky from 'ky';
 
// Mock fetch
vi.stubGlobal('fetch', vi.fn().mockResolvedValue(
  new Response(JSON.stringify({ id: 1, name: 'Alice' }), {
    status: 200,
    headers: { 'Content-Type': 'application/json' }
  })
));
 
describe('API Client', () => {
  it('should fetch user data', async () => {
    const user = await ky.get('https://api.example.com/users/1').json();
    expect(user).toEqual({ id: 1, name: 'Alice' });
  });
});

// lib/api.ts
import ky from 'ky';
 
export const api = ky.create({
  prefix: import.meta.env.VITE_API_BASE_URL,
  timeout: 10000,
  retry: { limit: 2 },
  hooks: {
    beforeRequest: [
      ({ request }) => {
        const token = localStorage.getItem('token');
        if (token) {
          request.headers.set('Authorization', `Bearer ${token}`);
        }
      }
    ],
    beforeError: [
      ({ error }) => {
        if (error instanceof HTTPError && error.response.status === 401) {
          // 全局处理 token 过期
          redirectToLogin();
        }
        return error;
      }
    ]
  }
});
 
// features/user/api.ts
import { api } from '@/lib/api';
import { UserSchema } from './schema';
 
export const userApi = {
  getById: (id: number) => api.get(`users/${id}`).json(UserSchema),
  list: () => api.get('users').json(UserSchema.array()),
  create: (data: CreateUserInput) =>
    api.post('users', { json: data }).json(UserSchema),
};

// schema/user.ts
import { z } from 'zod';
 
export const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  role: z.enum(['admin', 'user', 'guest']),
  createdAt: z.string().datetime()
});
 
export type User = z.infer<typeof UserSchema>;
 
// api/user.ts — 返回类型自动推导，无需手动标注
const users = await userApi.list();
// users: User[]

const api = ky.create({
  retry: {
    limit: 3,
    // 仅对幂等方法重试
    methods: ['get', 'put', 'head', 'options', 'trace'],
    // 不要对 4xx 客户端错误重试
    statusCodes: [408, 429, 500, 502, 503, 504],
    // 全局超时兜底
    maxRetryAfter: 30000
  }
});

// 基础实例
const baseApi = ky.create({ prefix: 'https://api.example.com' });
 
// 认证模块
const authApi = baseApi.extend({
  prefix: 'https://api.example.com/auth',
  hooks: {
    beforeRequest: [(request) => {
      request.headers.set('X-Auth-Module', 'auth');
    }]
  }
});
 
// 用户模块（继承认证）
const userApi = authApi.extend({
  prefix: 'https://api.example.com/users'
});

try {
  const data = await ky.get('/endpoint').json();
} catch (error) {
  if (isHTTPError(error) && error.response.status === 404) {
    // 处理 404
  }
}