langchain v3+ 在 vscode 中运行失败，90% 是因 python 解释器、导入路径与调试协议未对齐：须用子包导入（如 langchain_openai.chatopenai）、激活正确虚拟环境、启用 jupyter 内核，并在 launch.json 中设 "subprocess": true 和 "justmycode": false。
LangChain v3+ 在 VSCode 里跑不起来，90% 不是代码问题，而是 Python 解释器、导入路径和调试协议三者没对齐。直接 pip install langchain 后写 AgentExecutor 就报 AttributeError: module 'langchain' has no attribute 'llms'，说明你还在用 v2 的思维写 v3 的代码。
确认你装的是 LangChain v3+ 并验证 import 路径
v3 彻底废弃了 langchain.llms、langchain.chains 这类顶层模块。所有核心能力都下沉到子包，错一个 import 就直接失败。
- ✅ 正确写法：
from langchain_openai import ChatOpenAI（不是langchain.llms.OpenAI） - ✅ 正确写法：
from langchain_core.tools import tool（不是langchain.tools） - ✅ 正确写法：
from langgraph.graph import StateGraph（Agent 编排推荐用langgraph，不是langchain.agents） - 运行验证命令：
python -c "from langchain_core.runnables import Runnable"—— 报ModuleNotFoundError？说明环境没激活或装错了版本
VSCode 必须选对 Python 解释器且启用 Jupyter 内核
VSCode 底部状态栏显示的 Python 版本 ≠ 调试时实际用的解释器。launch.json 和 Jupyter Server 的 interpreter 设置拥有最高优先级，它们不一致就会“终端能跑，VSCode 调试就 ModuleNotFoundError”。
- 在命令面板（
Ctrl+Shift+P）执行Python: Select Interpreter，选中你虚拟环境里的python（Linux/macOS 是venv/bin/python，Windows 是venv\Scripts\python.exe） - 同样在命令面板执行
Jupyter: Select Interpreter to Start Jupyter Server，必须选**同一个**虚拟环境 - 检查
Python: Show Output面板：应同时出现Starting Jedi Python language server和Jupyter Server started两行日志 - 只装
ms-python.python不够，ms-toolsai.jupyter必须启用，否则断点进不了Runnable.invoke()内部
launch.json 调试配置必须显式启用 subprocess 并禁用 justMyCode
LangChain v3 的 Runnable 和 langgraph 大量依赖异步子进程调用与动态模块加载。默认调试配置会跳过这些调用栈，导致断点失效、变量无法 inspect。
- 在
.vscode/launch.json中添加关键参数："subProcess": true和"justMyCode": false -
"console": "integratedTerminal"推荐设置，方便实时看日志和 API 请求输出 - 不要依赖 VSCode 自动生成的配置，手动覆盖为：
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: Current File",
"type": "python",
"request": "launch",
"module": "pytest",
"justMyCode": false,
"subProcess": true,
"console": "integratedTerminal"
}
]
}
环境变量和 LLM 接入方式容易被忽略的细节
API Key 加载失败、模型初始化卡住、返回空响应，往往不是网络问题，而是环境变量没透传进调试进程，或用了已弃用的接入方式。
- 用
dotenv加载.env文件时，必须在脚本最开头调用：load_dotenv()，不能放在函数里或 import 之后 - OpenAI 接入必须用
langchain_openai.ChatOpenAI，v3 已移除langchain.llms.OpenAI；通义千问必须用langchain_community.llms.Tongyi，不是langchain.llms.Tongyi - 调试时如果发现
os.environ里没有OPENAI_API_KEY，检查launch.json是否漏了"envFile": "${workspaceFolder}/.env" - Windows 用户注意路径分隔符：虚拟环境路径含反斜杠时，VSCode 有时会解析失败，建议用正斜杠或双反斜杠
最常被绕开的其实是 subProcess: true 和 justMyCode: false 这两个开关——它们不是可选项，是 v3+ Agent 调试的硬性前提。哪怕 import 对了、解释器选对了，缺了这俩，断点永远停在入口函数，进不去 invoke() 或 stream() 内部。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
