Axios Params 序列化解决方案

Axios Params 序列化解决方案（paramsSerializer）

这篇笔记解决什么问题

当你遇到下面任一情况时，这篇笔记可以直接给出方案：

• 前端传了数组/对象，后端却"收不到"或结构不对
• 同一个参数在不同接口上格式要求不一致（[]、下标、重复 key）
• 你不确定该用 Axios 内置配置，还是引入 qs

30 秒选型（先看这里）

• 只用扁平对象 + 普通数组：用 Axios 内置 paramsSerializer.indexes
• 有复杂嵌套对象、严格后端协议：用 qs.stringify
• 想团队统一风格：在 axios 实例里一次性配置，不要散落在每个接口

paramsSerializer 是什么（定义）

paramsSerializer 用来控制 Axios 如何把 params 序列化成 URL query string。

• 作用对象：params
• 不作用于：data（请求体）、路径参数（如 /users/:id）
• 即使是 POST/PUT，只要传了 params，它也会生效

示例：

axios.post('/users', data, {
  params: { page: 1 },
})

Axios 内置三种序列化方式（数组）

假设：

params = { tags: ['red', 'blue'] }

配置	结果	适用场景
indexes: false	tags[]=red&tags[]=blue	常见 PHP/部分后端习惯（Axios 默认）
indexes: true	tags[0]=red&tags[1]=blue	后端需要明确索引
indexes: null	tags=red&tags=blue	后端按重复 key 解析数组

示例：

axios.get('/users', {
  params: { tags: ['red', 'blue'] },
  paramsSerializer: { indexes: null },
})

什么时候需要 qs

如果你有以下需求，建议直接用 qs：

• 嵌套对象较深（如 filter[name]=tom）
• 后端对参数格式有明确规范
• 需要统一控制空值、编码、数组格式、键排序

示例：

import qs from 'qs'

axios.get('/users', {
  params: { filter: { name: 'tom' }, tags: ['a', 'b'] },
  paramsSerializer: {
    serialize: (params) => qs.stringify(params, { arrayFormat: 'repeat' }),
  },
})

推荐落地方式（项目级）

把策略放到请求实例，统一生效：

const request = axios.create({
  baseURL: '/api',
  paramsSerializer: {
    indexes: null,
  },
})

一句话结论

paramsSerializer 只负责"params 怎么拼到 URL 上"；内置够用就别加库，复杂协议再用 qs。