如何URL编码NextJS的ParsedUrlQuery或转为URLSearchParams

首先明确场景边界：只有使用NextJS Pages Router时，从useRouter().query拿到的参数是ParsedUrlQuery类型；如果是App Router（v13+），直接从next/navigation引入useSearchParams，返回值本身就是标准URLSearchParams类型，无需额外转换。

针对ParsedUrlQuery的转换需求，有两种可直接落地的实现方式：

方式一：写通用转换函数，复用原有请求逻辑 #

ParsedUrlQuery的结构是Record<string, string | string[] | undefined>，直接遍历键值对塞入URLSearchParams实例即可，URLSearchParams会自动完成符合标准的URL编码，无需手动处理特殊字符转义，同时兼容多值参数场景：

import type { ParsedUrlQuery } from 'querystring';

function convertParsedQueryToSearchParams(query: ParsedUrlQuery): URLSearchParams {
  const searchParams = new URLSearchParams();
  for (const [key, value] of Object.entries(query)) {
    if (Array.isArray(value)) {
      // 处理 ?key=val1&key=val2 这类多值参数
      value.forEach(singleVal => searchParams.append(key, singleVal));
      continue;
    }
    if (value !== undefined) {
      searchParams.append(key, value);
    }
  }
  return searchParams;
}

使用时直接在调用请求方法前做转换即可，原有searchResources的代码不需要任何修改：

// Pages Router 调用示例
import { useRouter } from 'next/router';

function SearchPage() {
  const { query } = useRouter();
  const handleSearch = async () => {
    const res = await searchResources(convertParsedQueryToSearchParams(query));
    // 后续业务逻辑
  }
}

方式二：直接修改请求函数入参适配ParsedUrlQuery #

如果不需要兼容旧的URLSearchParams入参，可以直接把转换逻辑内置到请求函数里：

import type { ParsedUrlQuery } from 'querystring';

export async function searchResources(query: ParsedUrlQuery): Promise<SearchResourcesResponse> {
  const searchParams = new URLSearchParams();
  for (const [key, value] of Object.entries(query)) {
    if (Array.isArray(value)) {
      value.forEach(singleVal => searchParams.append(key, singleVal));
      continue;
    }
    if (value !== undefined) {
      searchParams.append(key, value);
    }
  }

  const response = await fetchWithTimeout(
    `${process.env.NEXT_PUBLIC_TUTHUB_SERVER_URL}/resources?${searchParams.toString()}`
  )
  const resources = await response.json();
  return resources;
};

注意事项 #

• 禁止手动拼接字符串、用JSON.stringify处理参数：前者容易漏处理特殊字符（中文、空格、&、=等）导致参数解析错误，后者生成的格式不符合URL查询参数标准，Express后端无法正常识别
• 必须处理数组类型的参数值，否则多值参数会被默认转成逗号拼接的字符串，后端拿到的参数格式不符合预期
• 用URLSearchParams生成的参数字符串完全符合浏览器URL的编码规范，和地址栏展示的格式完全一致，Express服务端可以直接通过req.query正常解析，不需要额外做解码处理。

内容的提问来源于stack exchange，提问作者Florian Walther