Claude Code 拒绝编辑 GBK 文件
截至 2026-10-13，Claude Code 的 Edit 与 NotebookEdit 是把整份文件按 UTF-8 写回的，2.1.296 之前解不出来的字节会被逐个换成替换字符 U+FFFD，这就是 GBK、Shift-JIS、Windows-1252 存的中文日文被改成乱码的原因；从 2.1.296（官方更新日志标注 October 9, 2026）起这类编辑直接拒绝，报错原文以 File is not valid UTF-8 开头，错误参考写明拒绝时什么都没写。稳妥的顺序是先用 file 这类通用命令确认编码，再备份并用 iconv 转成 UTF-8，最后才让 Claude Code 编辑；截至 2026-10-13，本页核对过的 settings、troubleshooting、common-workflows、checkpointing、terminal-config、overview 六页里没有指定文件编码的设置项。
更新于 2026-10-14
订阅额度用完或频繁 429？可以改用按 token 计费的 API，一把 key 接着用。
- 按 token 计费，实时单价见 /models
- 支付宝、微信支付、信用卡、加密货币均可付款
- 充值后自助开通、立刻生效
先弄清这四点
从哪个版本开始拒绝
官方更新日志把这句写在 2.1.296 一节，页面标注的版本日期是 October 9, 2026；GitHub 上 anthropics/claude-code 的 CHANGELOG.md 里同一句一字不差，但那份的版本号标题不带日期。
老版本写进去的字符
官方错误参考的原句是 Before v2.1.296, Edit and NotebookEdit applied such an edit and saved every byte they couldn't decode as U+FFFD.，并要还在用老版本的用户更新 Claude Code。
被拒绝时改了多少
官方说法是 Claude Code refused the change. Nothing was written, so the file is as it was.——拒绝时文件一个字节都不动。
确认编码的通用命令
file(1) 手册写明 -i 让 file 输出 MIME 类型串（手册例子里就是 text/plain; charset=us-ascii），--mime-encoding 只输出编码那一项；这是 Unix 工具的做法，不是 Claude Code 的参数。
为什么会改坏，现在为什么直接拒绝
截至 2026-10-13，官方文档把两件事都写明了。工具参考解释拒绝的原因：The tools refuse because they save the whole file back as UTF-8, which would replace every byte they can't decode with the replacement character U+FFFD.。官方更新日志称，2.1.296 之前 Edit 与 NotebookEdit 会替换文件里的每个非 ASCII 字符，错误参考写明解不出的字节会按 U+FFFD 保存，所以改一次文件，GBK 存的正文就会被一片 U+FFFD 取代。现在 Edit 与 NotebookEdit 改为拒绝并且不碰文件，报错原文点名 Windows-1252、Shift-JIS、GBK 三种遗留编码。还有一处要留意：错误参考写明判定看的是整份文件的字节，一个本该是 UTF-8 的文件只要混进一段非法字节序列，也会得到同一条报错。
官方更新日志的原句
Claude Code 更新日志 2.1.296 一节的原句是：Fixed Edit and NotebookEdit replacing every non-ASCII character in files that are not valid UTF-8 (Windows-1252, Shift-JIS, GBK); such edits are now refused。这一句在 code.claude.com 的 changelog 页与 GitHub 的 CHANGELOG.md 里逐字相同，官方页自己也写明它是从 CHANGELOG.md 生成的；版本日期 October 9, 2026 只在 code.claude.com 那份里有。更早两处改动也属编码：2.1.214（页面标注 July 18, 2026）修掉 Windows PowerShell 5.1 下 > 与 >> 写出 UTF-16LE 文件、其他工具按 UTF-8 读不出的问题；2.1.267（September 9, 2026）让 artifact 发布对不是合法 UTF-8 或含 U+FFFD 的文件报出带行列号的错误。
官方页里的三条时间线
Claude Code 2.1.214：修掉 Windows PowerShell 5.1 下 > 与 >> 写出别的工具读不成 UTF-8 的 UTF-16LE 文件，以及 Python 脚本读非 UTF-8 标准输入时崩溃于 UnicodeDecodeError；工具参考写明 Windows 这些编码行为需要 v2.1.214 或更新。
Claude Code 2.1.267：发布 artifact 时，页面文件不是合法 UTF-8 或含替换字符 U+FFFD 的报错改为点名要修的行与列；错误参考另写明 2.1.267 之前 Claude Code 不检查就上传，由服务端拒绝发布。
Claude Code 2.1.296：Edit 与 NotebookEdit 不再替换非 UTF-8 文件（Windows-1252、Shift-JIS、GBK）里的非 ASCII 字符，这类编辑改为直接拒绝。
已确认 vs 没有核实到的
已确认（官方页逐字可核）
以下内容都能对应到 2026-10-13 核对过的官方页面原文：2.1.296 那条修复的原句与版本日期 October 9, 2026；工具参考的 Non-UTF-8 files 一节写 Claude can't use NotebookEdit on a file that isn't valid UTF-8. The same goes for Edit, unless the file starts with a little-endian UTF-16 byte-order mark.，也就是 NotebookEdit 不能用于不是合法 UTF-8 的文件，Edit 同样，而以小端 UTF-16 字节顺序标记开头这个例外只写在 Edit 那一句上；同节还有「拒绝时不改文件」与「拒绝的原因是整份文件按 UTF-8 写回、解不出的字节会变成 U+FFFD」；错误参考里的报错原文与两条处理建议（用按该编码读写文件的 shell 命令来改，或转成 UTF-8 后再让 Claude 编辑）；2.1.296 之前会把解不出的字节写成 U+FFFD；Write 仍可整份替换这类文件，但替换后按 UTF-8 保存、原编码丢失。通用工具一侧：file(1) 的 -i 与 --mime-encoding、iconv(1) 的 -f/--from-code 与 -t/--to-code 以及 -l、-c、//TRANSLIT、//IGNORE，GNU libiconv 的编码表里列有 SHIFT_JIS、GBK、CP1252。
未证实与官方未说明
截至 2026-10-13，本页核对过的八份 Claude Code 官方文档页面——settings、troubleshooting、common-workflows、checkpointing、terminal-config、overview、errors 与 tools reference——里有三件事没写到，别把它们当成前提。第一，没有指定文件编码的方法：这八页里只有 errors 与 tools reference 讲到文件怎么解码，其余六页没有能选文件编码的设置项。第二，这些页面里也没有能让 Edit 按 GBK 写回的设置项或参数。第三，没有把已被 U+FFFD 换掉的正文自动还原的工具；错误参考在 artifact 发布那一节只说要重新按 UTF-8 保存，并把先前编辑、粘贴或转换丢掉的那个字符补回去。另外 file(1) 写明 Some of the encoding logic is hard-coded in encoding.c，它给的编码名只是线索。
官方给的两条路，两种不同的乱码
保持原编码 vs 转成 UTF-8
错误参考给了两条：想让文件留在当前编码，就按官方说法让 Claude 用读写该编码的 shell 命令来改；想继续用 Edit 工具，就把文件转成 UTF-8，或把那份本该是 UTF-8 的文件里的非法字节修掉，再让 Claude 重新编辑。差别在于只有转成 UTF-8 之后才用得上 Edit 与 NotebookEdit；保持原编码这条，错误参考只写了做法、没有给出具体命令，通用做法是 iconv -f GBK -t UTF-8 这类写法。
文件真被改坏 vs 终端只是显示乱码
官方 troubleshooting 页把 VS Code、Cursor、Devin Desktop 内置终端里出现的方块、糊成一片或字形不对归因于终端的 GPU 渲染器，办法是在 Claude Code 里运行 /terminal-setup 把 terminal.integrated.gpuAcceleration 设为 off，或在编辑器设置里改回来再重载窗口；这种情况下文件字节没变。文件真出问题时报的是 File is not valid UTF-8，且 2.1.296 起什么都没写；如果正文里已经有一片 U+FFFD，那是 2.1.296 之前的版本会写进去的字符。
按这个顺序处理
① 先确认编码。用通用命令 file 判类型：file(1) 写明 -i 输出 MIME 类型串（手册例子是 text/plain; charset=us-ascii）、--mime-encoding 只输出编码那一项；iconv(1) 的 -l 列出本机认识的编码名。这些是 Unix 工具的标准用法，不是 Claude Code 的参数。② 备份再转码。先复制一份原件，再用 iconv 指定输入与输出编码（手册写法是 iconv [ options ] [ -f from-encoding ] [ -t to-encoding ]，例子是 iconv -f ISO-8859-15 -t UTF-8 < input.txt > output.txt）。手册同时写明：转不过去的字符默认会让 iconv 终止，-c 丢弃它们，//TRANSLIT 用形近字符替代、替代不了的写成问号，//IGNORE 丢弃并在转换后报错；任何一种都会丢内容，所以转完要抽查正文并保留原件。③ 再让 Claude Code 编辑。先把 Claude Code 升到 2.1.296 或更新（官方文档对老版本只有一句 update Claude Code）；必须保持原编码时，按官方报错的提示让 Claude 用读写该编码的 shell 命令改；转成 UTF-8 之后 Edit 就能用了，但用 Write 整份替换会把文件存成 UTF-8、原编码丢失。
在 QCode 上
编码判定是 Claude Code 在你本机做的，与接哪个端点无关。接入只需要两个变量：ANTHROPIC_BASE_URL 填 https://api.qcode.cc/api，ANTHROPIC_AUTH_TOKEN 填控制台里以 cr_ 开头的密钥；站内的 ANTHROPIC_BASE_URL 配置页写明末尾不要带斜杠，也写明 Claude 模型只能走 Anthropic 协议的端点。截至 2026-10-13，claude-sonnet-5-5、claude-haiku-4-5-20251001 与 claude-opus-5-5 在 QCode 可调。按 token 计费，各模型单价见 /models。
常见问题
Claude Code 为什么把我的 GBK 文件改成一堆乱码，现在又直接拒绝编辑？
因为 Edit 与 NotebookEdit 把整份文件按 UTF-8 写回。工具参考写明原因是这些工具 save the whole file back as UTF-8, which would replace every byte they can't decode with the replacement character U+FFFD.，而 2.1.296 之前正是在做这种替换，所以 GBK、Shift-JIS 存的中文日文改一次就整片变成替换字符。2.1.296 起这类编辑被拒绝，官方更新日志的原句是 Fixed Edit and NotebookEdit replacing every non-ASCII character in files that are not valid UTF-8 (Windows-1252, Shift-JIS, GBK); such edits are now refused，错误参考写明拒绝时 Nothing was written, so the file is as it was.。屏幕上具体显示成什么由编辑器决定，官方点名的字符是 U+FFFD。
怎么确认一个文件到底是什么编码？
先用通用命令 file 看类别。file(1) 手册写明 -i 让 file 输出 MIME 类型串而不是平时的人类可读串，手册的例子就是 text/plain; charset=us-ascii，--mime-type 与 --mime-encoding 只打印其中一项。但把手册结果当线索：file 是靠字节区间与序列来判断文本类型的，手册自己写明一部分编码逻辑硬编码在 encoding.c 里，要确认就用 iconv 试转一遍、再人工抽查中日韩段落。截至 2026-10-13，本页核对过的 settings、troubleshooting、common-workflows、checkpointing、terminal-config 与 overview 六页里没有能显示或指定文件编码的 Claude Code 命令。
转成 UTF-8 的具体做法是什么，要不要先备份？
要先备份，转完再抽查。iconv(1) 的用法行是 iconv [ options ] [ -f from-encoding ] [ -t to-encoding ]，-f 用 from-encoding 作为输入字符编码、-t 用 to-encoding 作为输出编码，手册自己的例子是 iconv -f ISO-8859-15 -t UTF-8 < input.txt > output.txt；转 GBK 文件就把 from-encoding 换成 GBK。手册同时写明默认遇到转不过去的字符就终止，-c 丢弃这些字符，//TRANSLIT 用形近字符替代、替代不了就在输出里写成问号，//IGNORE 丢弃并在转换后报错——这几种都会丢内容，所以留好原件、逐段核对。这些都是通用 Unix 工具的写法，不是 Claude Code 的参数。
日文 Shift-JIS、西文 Windows-1252 也一样吗？
同一条规则。官方更新日志那句把 Windows-1252、Shift-JIS、GBK 并列写在同一句里；错误参考点名的也是这三种，工具参考举的例子是 Windows-1252 与 Shift-JIS。判定只看整份文件的字节能不能按 UTF-8 解码，官方文档写明哪怕一个本该是 UTF-8 的文件里只有一段非法字节序列，也会报同样的错。转码时按 GNU libiconv 编码表里列出的名字写：表里有 SHIFT_JIS、CP932、GBK、CP936、GB18030、BIG5 以及 CP1250 到 CP1257 一族，目标 UTF-8 也在表中。
在 QCode 上怎么把 Claude Code 接起来，单价看哪里？
两个变量。QCode 的 Claude Code 教程写的是 export ANTHROPIC_BASE_URL = https://api.qcode.cc/api 与 export ANTHROPIC_AUTH_TOKEN = cr_ 加上你的密钥，接入点对照表里 Claude Code 那一行填的也是 https://api.qcode.cc/api，站内的 ANTHROPIC_BASE_URL 配置页另写明末尾不要带斜杠、Claude 模型只能走 Anthropic 协议的端点。截至 2026-10-13，claude-sonnet-5-5、claude-haiku-4-5-20251001 与 claude-opus-5-5 在 QCode 可调。按 token 计费，各模型单价见 /models。
在国内、或者没有境外信用卡，怎么付款和开通？
用支付宝或微信支付就能充值。QCode 的付款方式文档写明充值页提供 Alipay（支付宝）、WeChat Pay（微信支付）、Credit / Debit Card（Visa / Mastercard / AMEX）、Apple Pay / Google Pay 与 Cryptocurrency（加密货币，多币种多网络、链上转账后人工核对）；QCode 是预付制，先充值再买套餐、套餐从余额里扣，站内页面也写明无需境外信用卡。同一文档写明充值页上的金额限制：人民币充值从 ¥100 起，美元充值区间是 $1 到 $2,000。注册后在控制台取 cr_ 开头的密钥，就能按上一条接到 Claude Code。
信息来源
Claude Code 官方更新日志（code.claude.com 的 changelog 页与 GitHub anthropics/claude-code 的 CHANGELOG.md）以及官方文档的 Error reference、Tools reference、Troubleshooting、Settings、Terminal configuration、Overview、Common workflows、Checkpointing 各页，均核对于 2026-10-13；通用工具一侧取 man7.org 的 file(1) 与 iconv(1) 手册页和 GNU libiconv 项目文档，也是 2026-10-13 核对；QCode 一侧取 docs.qcode.cc 的接入点与 API 路径、Claude Code 完整教程、付款方式三页，以及站内 Claude Code 国内使用、一键安装、ANTHROPIC_BASE_URL 配置三篇，均核对于 2026-10-13。
相关阅读
Claude Code 国内使用 2026：支付宝、微信支付
在国内接上 Claude Code 的完整步骤，含用支付宝或微信支付充值。
Claude Code 一键安装：macOS、Linux、Windows
官方安装命令与 QCode 一键脚本两条路线怎么走。
ANTHROPIC_BASE_URL 配置 2026：两个变量
把 Claude Code 指向自定义端点要设的两个变量与写法。
本页引语与步骤核对于 2026-10-13，以 Claude Code 官方更新日志与文档、file(1) 与 iconv(1) 手册页、GNU libiconv 文档以及 QCode 文档为准，官方页面随时调整，以官方页面为准。file 与 iconv 是通用 Unix 工具，本页只写它们的标准用法作为示例，它们不是 Claude Code 的参数；模型可用性以 /models 为准。