SVN 中文文件名報錯「Can't convert string from UTF-8」：Locale 配置修復指南

SVN checkout/update 遇到中文文件名報錯 svn: Can't convert string from 'UTF-8' to native encoding，本質是**客戶端 Locale 未設置為 UTF-8**，導致無法正確解碼倉庫中的 UTF-8 文件名。本文提供永久修復與臨時變通方案。

根因分析

• SVN 倉庫存儲文件名為 UTF-8
• 客戶端運行環境 LC_CTYPE/LANG 為 C 或 POSIX（默認 ASCII）
• SVN 嘗試將 UTF-8 文件名轉換為本地編碼失敗

方案一：永久修復 ~/.bash_profile（推薦）

# 編輯用戶環境配置
vim ~/.bash_profile

# 添加以下內容
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
export LANGUAGE=en_US.UTF-8

# 生效
source ~/.bash_profile
# 或重新登錄 SSH

方案二：針對性設置 LC_CTYPE（最小影響）

# 僅設置字符分類為 UTF-8，不影響貨幣、時間等格式
export LC_CTYPE=zh_CN.UTF-8
# 或
export LC_CTYPE=en_US.UTF-8

# 寫入 ~/.bashrc 使交互式 Shell 生效
echo 'export LC_CTYPE=zh_CN.UTF-8' >> ~/.bashrc
source ~/.bashrc

方案三：臨時命令行前綴（零配置）

# 單次命令生效
LC_CTYPE=zh_CN.UTF-8 svn up
LC_ALL=en_US.UTF-8 svn co https://svn.example.com/repo

# 腳本中使用
#!/bin/bash
export LC_CTYPE=zh_CN.UTF-8
svn update /path/to/wc

驗證 Locale 設置

locale
# 關鍵輸出應包含：
# LANG=en_US.UTF-8
# LC_CTYPE="en_US.UTF-8"  (或 zh_CN.UTF-8)
# LC_ALL=en_US.UTF-8 (若設置)

系統級配置（影響所有用戶）

# RHEL/CentOS/Fedora
localectl set-locale LANG=en_US.UTF-8

# Debian/Ubuntu
update-locale LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8

# 查看可用 Locale
locale -a | grep -i utf

# 安裝缺失 Locale (如 zh_CN.UTF-8)
# CentOS: yum install langpacks-zh_CN
# Ubuntu: apt install language-pack-zh-hans

進階：文件名編碼遷移（倉庫已存非 UTF-8 文件名）

# 1. 導出倉庫
svnadmin dump /path/to/repo > repo.dump

# 2. 轉換 dump 文件編碼 (需工具 svndumputf8 或 Python 腳本)
# 3. 創建新倉庫並導入
svnadmin create /path/to/newrepo
svnadmin load /path/to/newrepo < repo.dump.utf8

# 遷移僅副本
svn switch --relocate old_url new_url

常見誤區

• 只設置 LANG 不設置 LC_CTYPE： LC_CTYPE 優先級高於 LANG，必須同時設置或單獨設置 LC_CTYPE
• 設置 LC_ALL=C： 強制所有類別用 C locale，會導致中文顯示亂碼、SVN 無法處理 UTF-8 文件名
• 服務端也需設置： 只有客戶端需要正確 Locale，服務端只存儲 UTF-8 不做轉換

總結

核心修復：export LC_CTYPE=zh_CN.UTF-8 (或 en_US.UTF-8)。寫入 ~/.bash_profile 實現登錄永久生效，或在 CI/CD 腳本中 export 後調用 SVN。**現代項目建議遷移至 Git**，原生支援 UTF-8 文件名，避免 Locale 依賴痛苦。