1
const params = new URLSearchParams('tag=js&tag=node');
2
params.get('tag');                  // 'js'
3
params.getAll('tag');               // ['js', 'node']
4
Object.fromEntries(params).tag;     // 'node'

Object.fromEntries() 依 entries 建立物件屬性。同一個字串 key 再次出現，就會改寫同一個屬性；原本的 params 仍保留兩筆，遺失發生在新物件。

因此，前端用 get()、後端先轉物件再讀值，可能各自看到不同標籤。這個例子只證明 JavaScript API 的行為，不能推論 Laravel、PHP 或其他伺服器 parser 對重複參數的處理；前後端要另訂相同契約。

依欄位解析，再用 append 寫回#

下面假設 tag 可重複、page 最多出現一次且必須是正整數。readOne() 區分缺少、空字串與重複值；頁碼驗證才決定哪些值能接受。

1
function readOne(params, name) {
2
  const values = params.getAll(name);
3
  if (values.length > 1) throw new TypeError(`Duplicate ${name}`);
4
  return values.length === 0 ? null : values[0];
5
}
6

7
function parseFilters(query) {
8
  const params = new URLSearchParams(query);
9
  const rawPage = readOne(params, 'page');
10
  const pageText = rawPage === null ? '1' : rawPage;
11
  if (!/^[1-9]\d*$/.test(pageText)) throw new TypeError('Invalid page');
12
  const page = Number(pageText);
13
  if (!Number.isSafeInteger(page)) throw new TypeError('Invalid page');
14
  return { tags: params.getAll('tag'), page };
15
}
16

17
function serializeFilters({ tags, page }) {
18
  // 輸入是 parseFilters 產出的狀態；外部資料要先另做形狀驗證。
19
  const params = new URLSearchParams();
20
  for (const tag of tags) params.append('tag', tag);
21
  params.set('page', String(page));
22
  return params.toString();
23
}

這個範例只序列化標籤與頁碼，會捨棄其他欄位，適合已定義的篩選表單。它不會自動去除重複標籤，也沒有替你的產品限制標籤數量或允許清單。若要保留其他 query，應複製原 params，只刪除並重建自己擁有的欄位。

不要把 new URLSearchParams({ tag: ['js', 'node'] }) 當成多值序列化。Node.js 文件說明物件值會轉成字串，陣列在這裡成為 'js,node'。讀回得到的是一個值，不是兩個標籤。

用斷言確認往返沒有丟值#

把上面三個函式和以下程式碼存成 query-check.mjs，執行 node query-check.mjs。本文維護流程於 2026-10-10 使用 macOS、Node.js v24.13.0 執行這些測試，沒有向真實 API 發送請求。

1
import assert from 'node:assert/strict';
2

3
const params = new URLSearchParams('tag=js&tag=node');
4
assert.equal(params.get('tag'), 'js');
5
assert.equal(Object.fromEntries(params).tag, 'node');
6
assert.deepEqual(params.getAll('tag'), ['js', 'node']);
7

8
const state = parseFilters('tag=js&tag=node&page=2');
9
assert.deepEqual(parseFilters(serializeFilters(state)), state);
10
assert.throws(() => parseFilters('page=1&page=2'), /Duplicate page/);
11
assert.throws(() => parseFilters('page='), /Invalid page/);
12
assert.throws(() => parseFilters('page=1.5'), /Invalid page/);
13
assert.throws(() => parseFilters('page=9007199254740992'), /Invalid page/);
14
assert.equal(parseFilters('').page, 1);
15
assert.equal(readOne(new URLSearchParams('empty='), 'empty'), '');
16
assert.equal(readOne(params, 'missing'), null);
17

18
const collapsed = new URLSearchParams({ tag: ['js', 'node'] });
19
assert.deepEqual(collapsed.getAll('tag'), ['js,node']);
20
const replaced = new URLSearchParams(params);
21
replaced.set('tag', 'css');
22
assert.deepEqual(replaced.getAll('tag'), ['css']);
23
assert.deepEqual(params.getAll('tag'), ['js', 'node']);
24
console.log('重複值、頁碼與序列化往返檢查通過');