若要在 Python 中解碼 Base58，請將有效的 Bitcoin 字母表字串傳入 base58.b58decode()，並將傳回的值視為位元組，直到您明確以 UTF-8 解碼為止。

Python 的標準函式庫並未提供 Base58。實務上的做法是安裝第三方 base58 套件，先解碼成位元組，僅在這些位元組構成有效的 UTF-8 時才產生文字。這種順序能讓二進位資料保持無損，也能讓無效資料清楚呈現，而不是在不知情的情況下遭到變更。

此工作流程涵蓋原始的 Bitcoin 格式 Base58。它不會將成功解碼的字串視為已驗證的 Bitcoin 地址、私密金鑰或其他 Base58Check 物件。解碼字母表語法與驗證應用程式的校驗碼是兩個不同的作業。

base58 decode python
在 Python 中解碼 Base58：原始位元組與 UTF-8

Python Base58 解碼器會傳回什麼

Bitcoin Base58 字母表為 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz。其中包含 58 個符號，並刻意省略零、大寫 O、大寫 I 和小寫 l，因為它們可能與其他字元混淆。大寫與小寫字母仍然有所區別。

解碼器會將每個字元視為一個 58 進位數位，將這些數位結合成數值，再將該數值轉換為以 256 為基準的位元組。正確的原始資料解碼器也會針對編碼字串中每個開頭的 1 符號，還原一個開頭的零位元組。這點很重要，因為一般的整數轉換否則會遺失開頭的零位元組。

結果是位元組，而不會自動成為 Python 字串。這些位元組可能代表可讀的 UTF-8 文字，但 Base58 也能承載任意的二進位資料。因此，十六進位才是首先用來檢視資料的無損表示法。

使用 Python 解碼 Base58 字串

  1. 在您要執行程式的環境中安裝套件：

    python -m pip install base58

  2. 建立指令碼、匯入解碼器，並完全依照收到的內容指派 Base58 值：

    from base58 import b58decode

    value = "YOUR_BASE58_VALUE"

    請勿在值中加入空格、標點符號或引號。如果值來自檔案或 API 回應，請在不修剪編碼資料所含字元的情況下完整複製。

  3. 將字串解碼成位元組：

    raw = b58decode(value)

    當輸入包含 Base58 字母表以外的字元時，套件會引發 ValueError。在應用程式中，請擷取該例外並回報無效輸入，而不是刪除字元或猜測原本預期的字元。

  4. 以小寫十六進位檢視還原後的確切位元組：

    hex_bytes = raw.hex()

    print(hex_bytes)

    尤其當解碼後的內容是二進位資料時，這份十六進位輸出是最安全的比較值，可用來與原始來源的位元組進行比對。

  5. 僅在預期得到可讀文字時，才要求嚴格的 UTF-8 解讀：

    text = raw.decode("utf-8", errors="strict")

    print(text)

    如果位元組不是有效的 UTF-8，Python 會引發 UnicodeDecodeError。此時請保留十六進位結果。當確切位元組很重要時，請勿使用 errors="ignore" 或 errors="replace"，因為這些選項可能遺失資訊，或讓失敗的文字轉換看起來像是成功完成。

  6. 使用解碼後的值之前，請將十六進位內容與預期的來源位元組進行比對。當來源已知為文字時，也請確認其嚴格 UTF-8 解讀結果與原始措辭相符。

建立無相依套件的解碼器

如果安裝套件並不實用，可以使用 Python 的標準函式庫實作相同的原始 Bitcoin Base58 演算法。這個教學版本會驗證每個字元，並保留開頭的零位元組：

ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"

INDEX = {char: index for index, char in enumerate(ALPHABET)}

def decode_base58(value):

    if not isinstance(value, str):

        raise TypeError("Base58 input must be text")

    number = 0

    for char in value:

        if char not in INDEX:

             raise ValueError(f"Invalid Base58 character: {char!r}")

        number = number * 58 + INDEX[char]

    body = number.to_bytes((number.bit_length() + 7) // 8, "big") if number else b""

    zero_count = len(value) - len(value.lstrip("1"))

    return b"\x00" * zero_count + body

呼叫此函式會傳回位元組。例如，decode_base58(value).hex() 會顯示確切的十六進位序列，而 decode_base58(value).decode("utf-8", errors="strict") 僅適合有效的 UTF-8 內容。此實作會將空字串視為空位元組序列處理。

這個版本會反覆增長 Python 整數，因此正式環境或大型資料應使用專為有效處理大型輸入而設計的實作。它在此處的目的是明確呈現基準轉換與開頭零位元組規則。

解讀解碼後的輸出

在應用程式中傳遞解碼資料時，請將位元組解讀與文字解讀分開處理。兩種輸出回答的是不同的問題。

解碼結果 意義 處理方式
小寫十六進位 還原後位元組的確切序列 在處理二進位資料、進行比對或後續處理時予以保留
有效的 UTF-8 文字 這些位元組代表 Unicode 字元序列 當原始資料原本預期為可讀文字時，請使用文字
UnicodeDecodeError 這些位元組不構成有效的 UTF-8 保留十六進位輸出；不要以替代字元取代
字母表無效錯誤 輸入不是有效的原始 Base58 字串 重新複製該值，且不要加入空格、標點符號或替代字元

文字結果雖然方便，但不代表它是更權威的資料版本。即使沒有可用的文字解讀，十六進位仍維持精確無誤。

將原始 Base58 與 Base58Check 分開

原始 Base58 會將位元組對應至含有 58 個符號的字母表。Base58Check 則會加入應用程式專屬的位元組，包括版本位元組，以及根據雙重 SHA-256 計算的校驗碼。原始資料解碼器可以顯示 Base58Check 字串內部的位元組，但無法證明版本、資料內容或校驗碼對任何特定格式而言都是有效的。

下方介紹的瀏覽器工具僅實作原始 Base58。它不會加入或驗證 Base58Check 的版本位元組或校驗碼。因此，語法有效的結果並不能證明 Bitcoin 地址、延伸金鑰、WIF 值或其他含版本物件是有效的。當應用程式語意與校驗碼很重要時，請使用具格式感知能力的錢包或經審查的函式庫。

在瀏覽器中交叉檢查結果

請使用 Base58 編碼／解碼，不必再執行另一個指令碼即可驗證 Python 的結果。所有轉換都在瀏覽器中執行，且不會上傳任何輸入。解碼器一律會顯示還原後的十六進位位元組，並嘗試進行嚴格的 UTF-8 解讀。

  1. 若要測試值，請選擇「UTF-8 文字轉 Base58」，輸入一段已知且簡短的短語，然後執行編碼器。

  2. 檢查 Base58 結果，以及以小寫十六進位顯示的來源位元組。

  3. 複製確切且區分大小寫的 Base58 結果，不要加入空格或標點符號。

  4. 選擇「Base58 轉位元組與文字」，然後將原始值貼到解碼器中。

  5. 將還原後的十六進位位元組與預期位元組進行比對。只有在解碼器確認這些位元組是有效的 UTF-8 時，才使用文字面板。

瀏覽器介面會拒絕空白字元、標點符號、排除的 字元，以及字母表以外的任何其他符號，而不會在不知情的情況下清除或猜測內容。它也會保留開頭的零位元組，因此此工作流程適合用來精確測試 Python 中至關重要的行為。

處理邊界情況與大小限制

  • 確切複製各值：字母大小寫很重要。瀏覽器工具會拒絕 0、O、I 和 l，以及空白字元、標點符號和其他無效符號。

  • 因應空值：瀏覽器介面要求輸入不得為空。空的程式化測試向量在內部仍有定義，但沒有理由透過使用者介面提交空值。

  • 遵守瀏覽器大小限制：此工具最多接受 4,096 個解碼後的位元組。Base58 字串的限制會按比例設定，且輸出絕不會在不知情的情況下遭到截斷。對於大型二進位資料，請使用 Base64 等串流格式，以及專為處理檔案而設計的工具。

  • 不要將 Base58 視為保護機制：這是可逆轉換編碼，不是加密、雜湊、簽署、驗證或保密機制。任何擁有字母表的人都能還原位元組。請勿將有效的錢包機密貼到線上工具中，即使是只在本機處理的工具也一樣。

依照參考向量驗證行為

瀏覽器實作會依據 Bitcoin Core 官方的 Base58 編碼與解碼資料中的八個向量進行檢查。該測試集包含簡單的 ASCII 位元組、較長的短語、任意二進位資料，以及開頭有零位元組的情況。這些測試向量會驗證字母表順序、數值轉換及零位元組行為，而不是只依賴「先編碼再解碼」的往返測試。

獨立的 Bitcoin libbase58 專案也釐清了原始編碼與 Base58Check 之間的界線。測試您自己的 Python 實作時，請納入可讀文字、二進位位元組、無效字元及開頭零位元組所對應的預期十六進位內容。比較確切的十六進位內容，比只檢查解碼後的文字是否看似合理更可靠。

若想進一步瞭解，請參閱二進位轉文字轉換器：無須猜測即可解碼位元組。