VSCode 里 ModuleNotFoundError: No module named ‘encodings‘ 的排查与修复：从 Codex auth.json 改到 TaoToken

1. 早上打开 VSCodePython 解释器直接炸了你有没有遇到过这种场景昨天写代码还好好的今天早上打开 VSCode某个 Python 插件突然报错控制台里蹦出一行红字Fatal Python error: Py_Initialize: unable to load the file system codec ModuleNotFoundError: No module named encodings这个报错的意思是 Python 解释器在初始化阶段就挂了。encodings是 Python 标准库里的编码模块解释器启动时第一件事就是加载它。如果连这个模块都找不到说明 Python 的安装目录或者环境变量出了问题解释器根本没法正常启动。这个错误和普通的ModuleNotFoundError不一样。平时你import requests报错那是第三方包没装。但encodings是 Python 自带的它缺失意味着解释器本身的运行环境被破坏了。常见原因有这么几类Python 安装目录被部分删除或移动、PYTHONHOME和PYTHONPATH环境变量指向了错误路径、VSCode 里配置的解释器路径失效、或者某些插件比如 Remote SSH在远程环境里用了不完整的 Python。这篇文章会从环境变量排查开始一步步定位问题然后给出可复制的settings.json配置。最后我会演示一个容易被忽略的场景当你用 Codex 这类工具时auth.json里的 endpoint 配置也可能间接影响 Python 插件的运行环境把它改到 TaoToken 后重启验证报错消失。适合谁看在 VSCode 里写 Python、遇到解释器启动即报encodings缺失、想快速定位并修复的开发者。不管你是本地环境还是远程 SSH排查思路是通用的。2. 先搞清楚 encodings 缺失到底是谁的锅2.1 解释器启动流程里 encodings 的位置Python 解释器启动时会先初始化sys模块然后立刻加载encodings包来设置默认编码。这个加载过程依赖PYTHONHOME指向的目录结构。如果PYTHONHOME被设成了错误路径或者 Python 安装目录下的Lib/encodings文件夹丢失就会直接报No module named encodings。你可以把PYTHONHOME理解成 Python 的“家”。解释器启动时会去这个家里找Lib/encodings。如果家门牌号写错了或者家里被搬空了它就找不到东西。2.2 环境变量排查PYTHONHOME 和 PYTHONPATH先打开终端检查这两个变量# Windows PowerShell echo $env:PYTHONHOME echo $env:PYTHONPATH # macOS / Linux echo $PYTHONHOME echo $PYTHONPATH如果PYTHONHOME有值而且指向的路径不是你当前 Python 的安装目录那基本就是它了。正常情况这两个变量应该是空的让 Python 自己去找。很多人装完某些工具后环境变量被悄悄改了自己都不知道。修复方式把PYTHONHOME和PYTHONPATH清空然后重启 VSCode。# Windows PowerShell 临时清除当前会话 Remove-Item Env:PYTHONHOME -ErrorAction SilentlyContinue Remove-Item Env:PYTHONPATH -ErrorAction SilentlyContinue# macOS / Linux 临时清除 unset PYTHONHOME unset PYTHONPATH如果要永久清除Windows 去“系统属性 → 环境变量”里删掉macOS/Linux 去~/.bashrc或~/.zshrc里删掉对应的 export 行。2.3 检查 Python 安装目录是否完整如果环境变量没问题那就去看 Python 安装目录。以 Windows 为例默认路径大概是C:\Users\你的用户名\AppData\Local\Programs\Python\Python311。进去看看Lib\encodings文件夹在不在。我试过一次发现Lib目录下少了一半文件encodings文件夹直接没了。这种情况通常是安装过程被中断、或者杀毒软件误删导致的。解决办法就是重新安装 Python安装时勾选“Add Python to PATH”并且选择“Repair”或者直接覆盖安装。macOS 上用brew装的 Python可以用brew reinstall python3.11修复。Linux 上用apt或yum重装对应的 python3 包。2.4 VSCode 解释器路径配置环境变量和安装目录都正常但 VSCode 里还是报错那就要检查 VSCode 用的解释器路径对不对。打开命令面板CtrlShiftP输入Python: Select Interpreter看看当前选的是哪个。有时候 VSCode 会记住一个已经被删除或移动的解释器路径。你可以在.vscode/settings.json里显式指定{ python.defaultInterpreterPath: C:\\Users\\你的用户名\\AppData\\Local\\Programs\\Python\\Python311\\python.exe, python.terminal.activateEnvironment: true }macOS/Linux 的路径类似/usr/local/bin/python3.11或/opt/homebrew/bin/python3.11。改完之后重启 VSCode让配置生效。2.5 Codex auth.json 与 endpoint 的间接影响这里说一个容易被忽略的点。如果你在用 Codex 这类 AI 编码工具它的auth.json里配置了 endpoint 和 API Key。某些情况下Codex 插件会在 VSCode 启动时初始化自己的 Python 运行环境如果auth.json里的 endpoint 指向了一个不可用的地址插件初始化超时可能会连带影响 Python 插件的正常加载。auth.json的典型路径在~/.codex/auth.jsonWindows 是C:\Users\你的用户名\.codex\auth.json。你可以检查里面的base_url字段。如果它指向的是一个已经失效的地址建议改成 TaoToken 的 API 地址{ base_url: https://taotoken.net/api, api_key: 你的 TaoToken API Key, model: claude-sonnet-4-20250514 }注意base_url用https://taotoken.net/api不要加多余的路径。api_key去 TaoToken 控制台生成模型 ID 根据你实际用的填。改完之后重启 VSCode让 Codex 插件重新读取配置。这一步不是必须的但如果你排查完环境变量和解释器路径都没问题报错依然存在那值得检查一下 Codex 的配置。因为插件之间的初始化顺序和依赖关系有时候一个插件的超时会影响另一个插件的环境准备。3. 可复制的 settings.json 与 auth.json 配置3.1 VSCode settings.json 完整片段打开 VSCode 的设置搜索settings.json或者直接编辑.vscode/settings.json项目级或用户级settings.json。下面是一份可以直接复制的配置重点是解释器路径和终端环境{ python.defaultInterpreterPath: C:\\Users\\你的用户名\\AppData\\Local\\Programs\\Python\\Python311\\python.exe, python.terminal.activateEnvironment: true, python.terminal.activateEnvInCurrentTerminal: true, terminal.integrated.env.windows: { PYTHONHOME: , PYTHONPATH: }, terminal.integrated.env.osx: { PYTHONHOME: , PYTHONPATH: }, terminal.integrated.env.linux: { PYTHONHOME: , PYTHONPATH: } }这里把PYTHONHOME和PYTHONPATH显式设为空字符串覆盖掉系统里可能存在的错误值。python.defaultInterpreterPath换成你自己的实际路径。Windows 路径里的反斜杠要写成双反斜杠\\。如果你用的是虚拟环境比如venv或conda解释器路径指向虚拟环境里的python.exe{ python.defaultInterpreterPath: ${workspaceFolder}\\.venv\\Scripts\\python.exe }macOS/Linux 则是${workspaceFolder}/.venv/bin/python。3.2 Codex auth.json 配置片段auth.json的路径Windows:C:\Users\你的用户名\.codex\auth.jsonmacOS/Linux:~/.codex/auth.json内容格式{ base_url: https://taotoken.net/api, api_key: sk-你的TaoTokenKey, model: claude-sonnet-4-20250514, provider: anthropic }如果你用的是 Claude Code 或者 Cline 这类工具配置项名称可能略有不同但核心三件套是一样的Base URL、API Key、Model ID。Base URL 统一用https://taotoken.net/api不要加/v1或其他后缀。API Key 去 TaoToken 控制台的 API Keys 页面生成。3.3 环境变量清理脚本如果你不想手动去系统设置里删环境变量可以用脚本一次性清理。Windows PowerShell# 永久删除用户级环境变量 [Environment]::SetEnvironmentVariable(PYTHONHOME, $null, User) [Environment]::SetEnvironmentVariable(PYTHONPATH, $null, User)macOS/Linux 编辑~/.zshrc或~/.bashrc删掉包含PYTHONHOME和PYTHONPATH的行然后执行source ~/.zshrc改完这些配置后一定要完全重启 VSCode不是关窗口而是退出进程再打开。因为环境变量和解释器路径是在 VSCode 启动时读取的热重载不一定生效。4. 验证请求重启后确认报错消失4.1 用命令行验证 Python 解释器在 VSCode 的集成终端里直接运行python -c import encodings; print(encodings OK)如果输出encodings OK说明解释器本身没问题了。再跑一个更完整的检查python -c import sys; print(sys.executable); print(sys.getdefaultencoding()); import encodings; print(encodings.__file__)正常输出应该类似C:\Users\你的用户名\AppData\Local\Programs\Python\Python311\python.exe utf-8 C:\Users\你的用户名\AppData\Local\Programs\Python\Python311\Lib\encodings\__init__.py如果sys.executable指向的路径不对说明 VSCode 用的还是旧解释器回去检查settings.json里的python.defaultInterpreterPath。4.2 在 VSCode 里触发插件重新加载按CtrlShiftP输入Developer: Reload Window回车。这会重新加载整个 VSCode 窗口所有插件重新初始化。观察之前报错的插件是否还会弹出ModuleNotFoundError: No module named encodings。如果报错消失说明问题解决了。如果还在打开 VSCode 的控制台Help → Toggle Developer Tools看 Console 标签页里的具体报错信息。有时候报错会显示是哪个插件触发的以及它用的 Python 路径是什么。4.3 验证 Codex 插件是否正常连接如果你改了auth.json可以测试一下 Codex 插件是否能正常调用模型。在 VSCode 里打开 Codex 面板发一条简单的请求比如“写一个 Python 的 hello world”。如果能正常返回结果说明 endpoint 配置生效了。也可以直接用 curl 测试 TaoToken 的 API 连通性curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的TaoTokenKey \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: hello}] }如果返回正常的 JSON 响应说明 API Key 和 endpoint 都没问题。如果返回 401检查 Key 是否正确如果返回 404检查 URL 路径是否写错。4.4 成功结果的表现修复成功后你会看到这些现象VSCode 启动时不再弹出encodings报错Python 插件能正常识别解释器终端里python命令能正常进入交互模式Codex 或其他 AI 插件能正常调用模型。如果之前是 Remote SSH 场景还需要在远程主机上重复一遍环境变量检查和解释器路径配置。因为远程环境的 Python 是独立安装的本地的修复不影响远程。5. 本篇常见错排查401、local proxy failed、reading choices5.1 401 Unauthorized报错信息Error: 401 Unauthorized {error:{type:authentication_error,message:invalid x-api-key}}原因API Key 不对或者没传。检查auth.json里的api_key字段确认没有多余空格确认 Key 没有过期。去 TaoToken 控制台的 API Keys 页面重新生成一个替换进去。如果你用的是环境变量传 Key检查变量名是否正确。Anthropic 格式用x-api-key头OpenAI 格式用Authorization: Bearer。TaoToken 的 API 兼容 Anthropic 格式所以用x-api-key。5.2 local proxy failed报错信息Error: local proxy failed: dial tcp 127.0.0.1:7890: connect: connection refused原因某些工具会尝试走本地代理端口但代理没开。检查你的工具配置里是否有proxy或http_proxy设置。如果有把它删掉或者改成直连。TaoToken 的 API 地址是直接可访问的不需要额外代理。在auth.json里不要写proxy字段。在 VSCode 的settings.json里也检查一下http.proxy配置如果有指向本地端口的注释掉。5.3 reading choices 相关报错报错信息Error: reading choices: unexpected end of JSON input或者Error: reading choices: invalid character looking for beginning of value原因API 返回的不是 JSON可能是 HTML 错误页。通常是因为 endpoint 路径写错了请求打到了错误的地址。检查base_url是否写成了https://taotoken.net/api不要多加/v1或/chat/completions。TaoToken 的 SDK 会自动拼接路径你只需要填基础地址。另外检查model字段是否拼写正确。如果模型 ID 不存在API 也可能返回非 JSON 的错误页。5.4 OAuth 相关报错报错信息Error: OAuth token expired或者Error: failed to refresh OAuth token原因某些工具默认用 OAuth 认证但你配置的是 API Key。需要在配置里把认证方式改成 API Key。比如 Claude Code 的配置里把auth_type改成api_key然后填api_key字段。如果你用的是 Codex检查auth.json里是否有oauth相关字段删掉它们只保留base_url、api_key、model。5.5 三件套检查清单不管遇到哪种报错先对照这个清单检查配置项正确值常见错误Base URLhttps://taotoken.net/api多写/v1、写成首页地址API Keysk-开头从控制台生成有多余空格、Key 过期Model IDclaude-sonnet-4-20250514等拼写错误、用了不存在的模型Base URL 用https://taotoken.net/api不要加 UTM 参数。API Key 去 TaoToken 控制台生成。Model ID 根据你实际需要选不确定的话先用claude-sonnet-4-20250514测试。5.6 排查顺序建议遇到报错不要慌按这个顺序排查先看报错信息里的关键词是 401 就查 Key是 proxy 就查代理配置是 reading choices 就查 URL 路径。然后检查auth.json和settings.json里的三件套。最后用 curl 直接测试 API 连通性排除工具本身的干扰。如果 curl 能通但工具报错那就是工具配置问题。如果 curl 也不通那就是 Key 或网络问题。逐步缩小范围比盲目重装高效得多。6. 把 endpoint 改到 TaoToken 后的长期使用建议6.1 统一管理 API Key如果你同时在用多个 AI 编码工具Codex、Claude Code、Cline 等建议统一用同一个 TaoToken API Key。这样只需要在一个地方管理配额和账单不用每个工具单独充值。去 TaoToken 控制台的 API Keys 页面生成一个 Key然后在各个工具的配置里填同一个。控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content6.2 模型选择建议日常编码用claude-sonnet-4-20250514就够了速度快、成本低。复杂重构或架构设计可以切到claude-opus-4-20250514。如果你需要长上下文两个模型都支持 200K token。在auth.json里改model字段就能切换。改完重启 VSCode 生效。6.3 长期编码场景用 Coding Plan如果你每天都要用 AI 辅助编码按量计费可能不如包月划算。TaoToken 的 Coding Plan 提供固定额度的套餐适合长期高频使用的开发者。详情看https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content6.4 文档与接入参考不同工具的配置方式略有差异遇到不确定的地方可以查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentClaude Code 的专项配置参考https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content6.5 验证模型连通性改完配置后如果不确定是否生效可以用模型对话页面快速测试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content在页面里选好模型发一条消息能正常回复就说明 Key 和 endpoint 都没问题。然后再回到 VSCode 里配置对应的工具。6.6 定期检查环境变量最后提醒一句每次系统更新或安装新软件后环境变量可能会被修改。如果你再次遇到encodings报错先跑一遍echo $PYTHONHOME和echo $PYTHONPATH大概率是这两个变量又被设上了。把检查环境变量养成习惯能省下很多重装 Python 的时间。