如何在 Axios GET 请求中传递参数 (2026)

如何在 Axios GET 请求中传递参数 (2026)

Axios 是最受欢迎的 JavaScript HTTP 客户端，广泛应用于浏览器和 Node.js 环境。在处理 REST API 时，最常见的任务之一就是通过 GET 请求发送查询参数（Query Parameters）。

本指南将涵盖 Axios GET 请求中传递参数的各种方法，从基础用法到高级模式，如数组序列化、自定义序列化器和拦截器。

使用 `params` 对象传递基础参数

传递查询参数最整洁的方式是通过 params 配置选项：

import axios from 'axios';

const response = await axios.get('https://api.example.com/users', {
  params: {
    page: 1,
    limit: 20,
    sort: 'created_at'
  }
});

// 生成的 URL: https://api.example.com/users?page=1&limit=20&sort=created_at

Axios 会自动将 params 对象序列化为查询字符串并附加到 URL 后面。你无需手动构建 URL。

方法对比

以下是在 Axios GET 请求中传递参数的所有方式：

方法	示例	最佳适用场景
params 对象	axios.get(url, { params: {...} })	绝大多数场景
URL 字符串	axios.get(url + '?key=value')	简单、静态的参数
模板字符串	axios.get(`${url}?key=${value}`)	快速的一次性请求
URLSearchParams	axios.get(url, { params: new URLSearchParams(...) })	表单编码数据
paramsSerializer	自定义函数	复杂的序列化需求

传递不同的数据类型

字符串和数字

简单值会被直接序列化：

const response = await axios.get('/api/products', {
  params: {
    category: 'electronics',
    minPrice: 100,
    maxPrice: 500,
    inStock: true
  }
});

// URL: /api/products?category=electronics&minPrice=100&maxPrice=500&inStock=true

数组

默认情况下，Axios 使用方括号语法序列化数组：

const response = await axios.get('/api/products', {
  params: {
    ids: [1, 2, 3, 4, 5]
  }
});

// 默认 URL: /api/products?ids[]=1&ids[]=2&ids[]=3&ids[]=4&ids[]=5

不同的 API 期望的数组格式不同。可以使用 paramsSerializer 进行自定义：

import qs from 'qs';

// 逗号分隔: ?ids=1,2,3,4,5
const response = await axios.get('/api/products', {
  params: { ids: [1, 2, 3, 4, 5] },
  paramsSerializer: (params) => {
    return qs.stringify(params, { arrayFormat: 'comma' });
  }
});

// 重复键名: ?ids=1&ids=2&ids=3&ids=4&ids=5
const response2 = await axios.get('/api/products', {
  params: { ids: [1, 2, 3, 4, 5] },
  paramsSerializer: (params) => {
    return qs.stringify(params, { arrayFormat: 'repeat' });
  }
});

// 下标表示法: ?ids[0]=1&ids[1]=2&ids[2]=3
const response3 = await axios.get('/api/products', {
  params: { ids: [1, 2, 3, 4, 5] },
  paramsSerializer: (params) => {
    return qs.stringify(params, { arrayFormat: 'indices' });
  }
});

嵌套对象

对于接受嵌套参数的 API：

import qs from 'qs';

const response = await axios.get('/api/search', {
  params: {
    filter: {
      status: 'active',
      role: 'admin'
    },
    pagination: {
      page: 1,
      perPage: 25
    }
  },
  paramsSerializer: (params) => {
    return qs.stringify(params, { encode: false });
  }
});

// URL: /api/search?filter[status]=active&filter[role]=admin&pagination[page]=1&pagination[perPage]=25

Null 和 Undefined 值

默认情况下，Axios 会忽略 undefined 值，但会包含 null：

const response = await axios.get('/api/users', {
  params: {
    name: 'John',
    email: undefined,  // 从 URL 中消失
    phone: null         // 包含在 URL 中，表现为 ?phone=
  }
});

// URL: /api/users?name=John&phone=

如果要同时跳过 null 和 undefined：

const cleanParams = (params) => {
  return Object.fromEntries(
    Object.entries(params).filter(([_, v]) => v != null)
  );
};

const response = await axios.get('/api/users', {
  params: cleanParams({
    name: 'John',
    email: undefined,
    phone: null
  })
});

// URL: /api/users?name=John

使用 URLSearchParams

原生 URLSearchParams API 可以直接与 Axios 配合使用：

const params = new URLSearchParams();
params.append('search', 'laptop');
params.append('category', 'electronics');
params.append('category', 'computers'); // 支持重复的键名

const response = await axios.get('/api/products', { params });

// URL: /api/products?search=laptop&category=electronics&category=computers

这在需要动态添加参数时非常有用：

const params = new URLSearchParams();

// 根据条件构建参数
if (searchTerm) params.append('q', searchTerm);
if (category) params.append('category', category);
if (minPrice) params.append('min_price', minPrice);
if (maxPrice) params.append('max_price', maxPrice);

const response = await axios.get('/api/search', { params });

通过拦截器设置默认参数

对于每个请求都需要包含的参数（如 API 密钥或语言设置），请使用请求拦截器：

const apiClient = axios.create({
  baseURL: 'https://api.example.com'
});

apiClient.interceptors.request.use((config) => {
  config.params = {
    api_key: process.env.API_KEY,
    locale: 'en',
    ...config.params  // 与请求特定的参数进行合并
  };
  return config;
});

// 现在每个请求都会包含 api_key 和 locale
const response = await apiClient.get('/users', {
  params: { page: 1 }
});

// URL: https://api.example.com/users?api_key=xxx&locale=en&page=1

在实例上设置默认参数

你也可以在创建 Axios 实例时设置默认参数：

const apiClient = axios.create({
  baseURL: 'https://api.example.com',
  params: {
    api_key: process.env.API_KEY,
    format: 'json'
  }
});

// 这里的默认值将与单个请求的参数合并
const response = await apiClient.get('/data', {
  params: { page: 2 }
});

// URL: https://api.example.com/data?api_key=xxx&format=json&page=2

TypeScript: 类型化参数

对于 TypeScript 项目，请为你的参数定义接口：

interface UserSearchParams {
  q?: string;
  page: number;
  limit: number;
  role?: 'admin' | 'user' | 'moderator';
  active?: boolean;
}

async function searchUsers(params: UserSearchParams) {
  const response = await axios.get<{ users: User[]; total: number }>(
    '/api/users',
    { params }
  );
  return response.data;
}

// 类型安全的参数传递
const result = await searchUsers({
  q: 'john',
  page: 1,
  limit: 20,
  role: 'admin'
});

转义特殊字符

Axios 会自动对参数进行编码，但某些 API 可能需要特定的编码方式：

// Axios 自动处理编码
const response = await axios.get('/api/search', {
  params: {
    q: 'hello world & goodbye',  // 编码为 hello%20world%20%26%20goodbye
    tag: 'c++'                     // 编码为 c%2B%2B
  }
});

// 如果参数已经编码过，为了防止二次编码：
const response2 = await axios.get('/api/search', {
  params: { q: 'pre-encoded%20value' },
  paramsSerializer: (params) => {
    return qs.stringify(params, { encode: false });
  }
});

实战案例：分页 API 客户端

这是一个结合了多种技术的完整示例：

import axios from 'axios';
import qs from 'qs';

const api = axios.create({
  baseURL: 'https://api.example.com/v2',
  timeout: 10000,
  paramsSerializer: (params) => {
    return qs.stringify(params, {
      arrayFormat: 'comma',
      skipNulls: true
    });
  }
});

// 为每个请求添加 auth token
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('auth_token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// 带过滤器的分页获取
async function fetchProducts(filters = {}) {
  const { data } = await api.get('/products', {
    params: {
      page: filters.page || 1,
      per_page: filters.perPage || 20,
      sort_by: filters.sortBy || 'created_at',
      order: filters.order || 'desc',
      categories: filters.categories,   // 数组：序列化为逗号分隔
      min_price: filters.minPrice,
      max_price: filters.maxPrice,
      search: filters.search
    }
  });

  return data;
}

// 使用示例
const products = await fetchProducts({
  page: 2,
  categories: ['electronics', 'gadgets'],
  minPrice: 50,
  sortBy: 'price'
});

// URL: /products?page=2&per_page=20&sort_by=price&order=desc&categories=electronics,gadgets&min_price=50

常见错误提示

错误	问题	修正方法
将参数放在 data 中	GET 请求会忽略 data 字段	使用 params 而非 data
手动构建 URL	处理特殊字符时容易出错	使用 params 对象
忘记设置 paramsSerializer	默认数组格式可能与 API 不匹配	为实例设置序列化器
未处理空值	会发送 ?key= 或 ?key=undefined	过滤掉 null/undefined 值
二次编码	出现 %2520 而非 %20	如果已预编码，使用 encode: false

总结

Axios 中的 params 对象能够处理绝大多数 GET 请求的参数需求。对于涉及数组、嵌套对象或自定义序列化的复杂场景，请将 params 与 qs 库以及 paramsSerializer 结合使用。当相同的参数需要伴随每个请求时，利用拦截器和实例默认值来保持代码的 DRY（简洁）。

如果你正在构建调用 AI API 进行图像生成、视频创建或语音合成的应用，欢迎免费试用 Hypereal AI —— 提供 35 个积分，无需信用卡。我们的 REST API 遵循本指南中涵盖的所有规范，可以轻松地与 Axios 或任何 HTTP 客户端集成。