JSON 扁平化

關於 GeekFormat

點擊轉換來扁平化或還原巢狀 JSON

分隔符:

保留陣列

最大深度:(0=unlimited)

線上 JSON 扁平化與還原工具，一鍵將巢狀 JSON 轉為點號分隔的單層鍵值對，支援自訂分隔符、陣列索引展開與反向還原，本地處理更安全。

適用場景

MongoDB 查詢與聚合：把巢狀 JSON 轉為點號扁平結構後，直接用於 find 查詢、update 更新與聚合管線，無需手寫路徑
CSV/Excel 匯出：把多層巢狀物件扁平化後，作為欄位標題匯入 Pandas DataFrame 或 Excel，每筆資料保持一行
Elasticsearch 索引：扁平文件更適合搜尋引擎儲存與查詢，把巢狀陣列欄位全部展開成單層鍵值對
API 介面除錯：對照請求與回應的巢狀結構差異，扁平化後欄位名更直覺，便於定位欄位缺失與型別錯誤
設定檔前置處理：把 package.json、settings.json 等巢狀設定扁平化為環境變數形式，方便注入 Docker 或 CI 流程
日誌與監控：將複雜的巢狀日誌事件扁平化後寫入資料倉儲，便於按欄位聚合與視覺化

使用方法

把需要處理的 JSON 貼到左側輸入框，或點擊上傳按鈕選擇本地 .json 檔，也可以先點擊範例載入一份巢狀樣本
在工具列切換「扁平化」或「還原」模式，並在底部選項區設定分隔符、陣列處理方式與最大展開深度
工具會自動即時處理，右側輸出區即時顯示結果與鍵數量、最大深度統計
點擊複製按鈕把結果寫入剪貼簿，或點擊下載按鈕儲存為 .json 檔到本地

功能特點

雙向轉換：支援 JSON 扁平化與反扁平化，隨時在巢狀與單層之間無損切換
自訂分隔符：預設點號，可改用底線、斜線、雙底線或任意字元，適配不同下游系統
陣列處理可設定：可選擇展開為索引鍵（如 items.0、items.1）或整體保留為單值，涵蓋表格化與設定兩類場景
最大深度限制：可設定展開深度上限，避免深層巢狀產生過長的鍵名
即時統計：處理後即時顯示鍵數量與最大深度，方便評估輸出規模
本地隱私處理：所有解析與轉換在瀏覽器端完成，JSON 資料零上傳，適合敏感介面與正式環境設定
檔案上傳與範例：支援上傳 .json 檔，也提供一鍵載入範例資料，快速驗證轉換效果
複製與下載：處理結果可一鍵複製到剪貼簿或下載為標準 .json 檔，方便二次處理

程式碼範例

JavaScript 實作 JSON 扁平化

javascript

function flatten(obj, prefix = '', sep = '.') {
  return Object.entries(obj).reduce((acc, [key, value]) => {
    const newKey = prefix ? `${prefix}${sep}${key}` : key;
    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
      Object.assign(acc, flatten(value, newKey, sep));
    } else {
      acc[newKey] = value;
    }
    return acc;
  }, {});
}

flatten({ user: { name: 'Alice', contact: { email: 'a@x.com' } } });
// => { 'user.name': 'Alice', 'user.contact.email': 'a@x.com' }

Python 實作 JSON 扁平化

python

def flatten(obj, parent_key='', sep='.'):
    items = {}
    for key, value in obj.items():
        new_key = f"{parent_key}{sep}{key}" if parent_key else key
        if isinstance(value, dict):
            items.update(flatten(value, new_key, sep))
        else:
            items[new_key] = value
    return items

import json
print(json.dumps(flatten({'user': {'name': 'Alice'}}), indent=2))
# => {"user.name": "Alice"}

命令列使用 jq 扁平化

bash

# 將巢狀 JSON 轉為點號扁平結構
jq '[paths(scalars) as $p | {"key": $p | join("."), "value": getpath($p)}] | from_entries' data.json

# 將扁平 JSON 還原為巢狀
# 需搭配 jq 1.7+ 與第三方過濾器，或直接使用本工具的「還原」模式

常見問題

什麼是 JSON 扁平化？什麼時候需要用？

JSON 扁平化是把多層巢狀的物件或陣列轉換為單層鍵值對的過程，巢狀鍵名透過分隔符（預設點號）拼接，例如 {"user":{"name":"Alice"}} 會變成 {"user.name":"Alice"}。當你需要把巢狀 JSON 匯出為 CSV、寫入 MongoDB 點號查詢、做 Elasticsearch 索引、設定成環境變數，或介接只接受扁平鍵的下游系統時，就需要 JSON 扁平化。

扁平化後的 JSON 還能還原成巢狀結構嗎？

可以。本工具內建反扁平化模式，只要分隔符設定一致，就能無損地把扁平鍵值對還原回原本的巢狀物件與陣列，且會自動辨識連續整數索引（0、1、2…）並還原為陣列，無需手動指定。

支援自訂分隔符嗎？陣列要怎麼處理？

支援。分隔符可以是點號、底線、斜線、雙底線或任意字元，最長 3 位元。陣列有兩種處理方式：預設按數字索引展開為 items.0、items.1；也可勾選保留整個陣列作為單值。還可以設定最大展開深度（0 表示不限制），超過指定層級的巢狀會作為整體保留，避免鍵名過長。

線上處理 JSON 會洩漏隱私嗎？

不會。所有解析、扁平化與反扁平化操作都在你的瀏覽器本地完成，JSON 資料不會經過任何伺服器上傳。正式環境 API、上線設定與個人資料全程不離開你的裝置，可以放心使用。

JSON 扁平化在 MongoDB 裡怎麼用？

MongoDB 預設使用點號語法存取巢狀欄位，例如查詢 user.contact.email 等於 alice@example.com 的文件，指令為 { "user.contact.email": "alice@example.com" }。用本工具把巢狀 JSON 轉為點號扁平結構後，對應的鍵名可以直接複製到 find 查詢、update 更新與聚合管線，省下手寫路徑的成本。

扁平化之後怎麼匯出 CSV 或 Excel？

扁平化的輸出本身就是單層鍵值對，每筆資料的所有欄位都在同一層，可以直接複製到我們的 JSON 轉 CSV 工具，或在 Excel/Pandas 裡以點號鍵名作為欄位標題匯入。對於陣列裡的物件，建議用最大深度限制或保留陣列整體，避免一筆記錄被拆成多行。

什麼情境適合用底線或斜線當分隔符？

點號（user.address.city）最通用，適合 JS 物件與 MongoDB 查詢；底線（user_address_city）適合 SQL 欄位名稱、Python 變數名稱與環境變數；斜線（user/address/city）類似檔案路徑，常用於 REST API 路徑參數；雙底線（user__address__city）適合 Django 設定等本身就含底線的情境。

鍵名本身帶點號或底線會衝突嗎？

會。例如原始鍵名是 user.name，再以點號為分隔符扁平化後會變成 user.name.name，反扁平化時會拆成 user → name → name 兩層。因此遇到鍵名含分隔符字元時，請改用不會出現在鍵名裡的分隔符，例如斜線或雙底線，或在操作前對原始鍵名做轉義/替換。

陣列裡的物件會被展開成什麼形式？

預設按數字索引展開，例如 orders 陣列裡的兩個物件會變成 orders.0.id、orders.0.total、orders.1.id、orders.1.total。如果你的下游只想要一維表，這種結構直接對應 CSV 的多行資料。反扁平化時，連續整數索引（0、1、2…）會自動還原為陣列，無需額外開關。

處理很大的 JSON 會卡嗎？

本工具在瀏覽器中處理，常見介面回應（幾十到幾百 KB）都能秒級完成；幾 MB 以上的超大檔案建議優先在本地命令列用 jq 處理，避免瀏覽器記憶體壓力。若仍要線上處理，可先壓縮或精簡欄位再貼上，或拆成多個批次分別扁平化。

最大深度限制有什麼用？

最大深度限制可以把展開控制在指定層級，超過層級的巢狀物件會作為整體保留為一個值。它有兩個常見用途：一是防止過深的設定層級產生冗長的鍵名；二是保護下游資料庫的欄位名長度限制（如某些 SQL Server 欄位名上限 128 字元）。預設 0 代表不限制，按需調整即可。

轉換後的結果可以儲存或重複使用嗎？

可以。處理完成後可以一鍵複製結果到剪貼簿，也可以直接下載為標準的 .json 檔。整個過程都在本地完成，不需要註冊帳號，也不會被伺服器端快取。

故障排查

提示「輸入不是合法的 JSON」

原因：JSON 文字存在語法錯誤，如缺引號、逗號多餘、括號未閉合、布林值寫成 Python 風格的 True/False。解法：先用本工具集的 JSON 格式化/校驗工具檢查語法；布林與 null 必須小寫且不加引號，鍵名必須用雙引號。

扁平化後鍵名衝突，反扁平化時層級錯亂

原因：原始鍵名本身就包含所選分隔符（例如 user.name 用點號分隔時），導致拆分時多出一層。解法：改用不會出現在鍵名裡的分隔符（斜線、雙底線或自訂字元），或者在操作前對原始鍵名做轉義/替換。

陣列被展開後匯出 CSV 變成多行

原因：預設會把陣列元素按數字索引展開，每個陣列元素都產生一組鍵值對，與其他欄位交叉後形成多筆記錄。解法：若要一行一物件，請勾選「保留整個陣列作為單值」，或在 CSV 工具指定陣列欄位不展開；若需要每個陣列元素一行，那是預期行為。

反扁平化結果不是預期的陣列

原因：只有鍵名裡出現連續整數索引（0、1、2…）時才會被還原為陣列，如果鍵名是 orders.first、orders.second 則會被識別為物件。解法：重新扁平化時不要改寫數字索引，或者手動把陣列欄位的鍵名改成 orders.0、orders.1 的純數字形式再還原。

鍵名過長或資料庫欄位名被截斷

原因：深度巢狀 JSON 扁平化後，路徑鍵可能超過下游 SQL Server、PostgreSQL 等資料庫的欄位名長度限制。解法：在工具選項裡設定「最大展開深度」，超過指定層級的巢狀會作為整體保留；或拆解巢狀結構、對深路徑鍵做重新命名後再處理。

瀏覽器處理大檔案卡頓或當機

原因：超大 JSON（幾十 MB 以上）會佔用大量瀏覽器記憶體，導致頁面無回應或當機。解法：把檔案拆分後再處理，或改用命令列工具（如 jq、flatten-json、Python 腳本），本工具更適合處理介面回應、設定檔、日誌條目等常見規模的資料。