开发环境搭建

上一篇搭好了 Python 环境，这一篇把 LangGraph 开发要用的全部依赖装齐，配好 VSCode，并写一个验证脚本确认一切就绪。

一、安装 VSCode 与 Python 扩展

下载 Visual Studio Code，安装。
打开 VSCode，左侧扩展面板（Ctrl+Shift+X）搜索并安装：
- Python（Microsoft 官方，必装）
- Pylance（Microsoft 官方，类型检查与智能提示，会随 Python 扩展自动装上）
- Jupyter（如需在 notebook 里跑示例，必装）
- Ruff（Astral 出的 linter + formatter，可选但推荐）
- Even Better TOML（编辑 pyproject.toml 高亮，可选）
在 VSCode 右下角状态栏点击 Python 版本，选中你项目 .venv 里的解释器（路径形如 d:\xxx\.venv\Scripts\python.exe）。

settings.json 推荐配置（项目根目录 .vscode/settings.json）：

json

{
  "python.defaultInterpreterPath": ".venv\\Scripts\\python.exe",
  "python.analysis.typeCheckingMode": "basic",
  "python.analysis.autoImportCompletions": true,
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff"
  }
}

二、Jupyter 安装与用途

Jupyter Notebook 适合交互式探索、试参数、看中间结果。学 LangGraph 时用 Jupyter 单步调试图的状态非常方便。

bash

# 用 uv
uv add jupyter ipykernel --dev
# 或用 pip
pip install jupyter ipykernel -i https://pypi.tuna.tsinghua.edu.cn/simple

安装后，VSCode 里新建 xxx.ipynb 文件就能直接跑。也可以命令行启动：

bash

jupyter lab

三、安装核心依赖

创建项目目录并初始化：

bash

mkdir my-langgraph
cd my-langgraph

# 用 uv 初始化
uv init
# 会生成 pyproject.toml 和 .python-version

pyproject.toml 初始内容大致如下：

toml

[project]
name = "my-langgraph"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = []

添加 LangGraph 全套依赖：

bash

# 核心包
uv add langgraph langchain-core langchain-openai langchain-community

# 持久化（后续 SQLite checkpointer 要用）
uv add langgraph-checkpoint-sqlite

# 环境变量加载
uv add python-dotenv

# 开发依赖（可选）
uv add ruff jupyter --dev

依赖清单说明：

包名	作用
`langgraph`	图编排引擎，本教程主角
`langchain-core`	LangChain 核心抽象（消息、工具、Runnable）
`langchain-openai`	OpenAI 模型封装（ChatOpenAI、OpenAIEmbeddings）
`langchain-community`	社区集成（各种向量库、加载器）
`langgraph-checkpoint-sqlite`	SQLite 持久化检查点
`python-dotenv`	从 `.env` 读取环境变量

四、API 密钥管理

我们以 OpenAI 为例。其他兼容 OpenAI 接口的模型（DeepSeek、Moonshot、智谱等）配置方式完全一样，只改 base_url 和 api_key。

在项目根目录建 .env 文件：

bash

# .env
OPENAI_API_KEY=sk-你的真实key
# 如果用兼容服务，再加这两行
OPENAI_BASE_URL=https://api.deepseek.com
MODEL_NAME=deepseek-chat

注意：

.env 绝不能提交到 git——把 .env 加进 .gitignore。
不要把 key 硬编码到代码里。
多人协作时，复制一份 .env.example（去掉真实值）提交，每人各自填自己的。

五、.gitignore 模板

在项目根目录创建 .gitignore：

text

# Python
__pycache__/
*.py[cod]
*.egg-info/
.pytest_cache/
.mypy_cache/
.ruff_cache/

# 虚拟环境
.venv/
venv/

# 环境变量与密钥
.env
.env.local
*.key

# Jupyter
.ipynb_checkpoints/

# 数据库文件（SQLite checkpointer）
*.db
*.sqlite
*.sqlite3

# IDE
.vscode/
.idea/

# 系统
.DS_Store
Thumbs.db

六、项目结构建议

text

my-langgraph/
├── .env                  # 密钥（不提交）
├── .env.example          # 密钥模板（提交）
├── .gitignore
├── .python-version       # Python 版本
├── pyproject.toml        # 依赖声明
├── uv.lock               # 锁定依赖版本
├── README.md             # 项目说明（可选）
├── src/
│   └── my_project/
│       ├── __init__.py
│       ├── graph.py      # 图定义
│       ├── nodes.py      # 节点函数
│       ├── state.py      # 状态定义
│       └── tools.py      # 工具函数
├── examples/
│   └── hello.py          # 示例脚本
└── tests/
    └── test_graph.py     # 测试

学习阶段可以简化，所有代码塞一个文件先跑通，再慢慢拆分。

七、验证脚本

在项目根目录建 test_env.py：

python

# test_env.py —— 验证环境是否就绪
import os
from dotenv import load_dotenv

# 加载 .env
load_dotenv()

print("=" * 50)
print("环境检查")
print("=" * 50)

# 1. 检查 Python 版本
import sys
print(f"Python 版本: {sys.version}")

# 2. 检查关键包是否装好
def check_import(name):
    try:
        mod = __import__(name)
        ver = getattr(mod, "__version__", "未知")
        print(f"  [OK] {name} ({ver})")
        return True
    except ImportError as e:
        print(f"  [缺失] {name}: {e}")
        return False

print("\n依赖检查:")
check_import("langgraph")
check_import("langchain_core")
check_import("langchain_openai")
check_import("langchain_community")

# 3. 检查 API Key
print("\n密钥检查:")
api_key = os.getenv("OPENAI_API_KEY")
if api_key:
    print(f"  [OK] OPENAI_API_KEY 已加载 (前 8 位: {api_key[:8]}...)")
else:
    print("  [缺失] OPENAI_API_KEY 未设置，请检查 .env 文件")

base_url = os.getenv("OPENAI_BASE_URL")
if base_url:
    print(f"  [INFO] OPENAI_BASE_URL = {base_url}")

# 4. 试调一次 LLM（可选，需要联网和有效 Key）
if api_key:
    print("\nLLM 调用测试:")
    try:
        from langchain_openai import ChatOpenAI
        llm = ChatOpenAI(
            model=os.getenv("MODEL_NAME", "gpt-4o-mini"),
            api_key=api_key,
            base_url=base_url,  # None 时用 OpenAI 默认
        )
        resp = llm.invoke("说一句你好")
        print(f"  [OK] LLM 返回: {resp.content}")
    except Exception as e:
        print(f"  [失败] {e}")

print("\n" + "=" * 50)
print("环境检查完成")

运行：

bash

# uv
uv run python test_env.py
# 或 venv 激活后
python test_env.py

八、预期输出

一切正常时输出类似：

text

==================================================
环境检查
==================================================
Python 版本: 3.12.4 (main, ...)

依赖检查:
  [OK] langgraph (0.2.60)
  [OK] langchain_core (0.3.20)
  [OK] langchain_openai (0.2.10)
  [OK] langchain_community (0.3.10)

密钥检查:
  [OK] OPENAI_API_KEY 已加载 (前 8 位: sk-1234...)
  [INFO] OPENAI_BASE_URL = https://api.deepseek.com

LLM 调用测试:
  [OK] LLM 返回: 你好！有什么我可以帮你的吗？

==================================================
环境检查完成

看到这些就说明环境完全就绪，可以开始写代码了。

九、常见踩坑

版本冲突：装新包时出现 ResolutionImpossible。通常是某个包要求互相冲突的依赖。解决：用 uv/poetry 的 lock 文件管理，或显式锁定某个版本。
网络超时：直连 PyPI 慢或失败。务必配清华源（见上一篇），或临时 -i https://pypi.tuna.tsinghua.edu.cn/simple。
API Key 未加载：代码里 os.getenv("OPENAI_API_KEY") 返回 None。原因：① 没调 load_dotenv()；② .env 不在工作目录；③ .env 里 key 前后有空格或引号；④ 文件名写成了 .env.txt（Windows 默认隐藏扩展名）。
OPENAI_BASE_URL 没设：用 DeepSeek 等兼容服务却没设 base_url，会默认打到 OpenAI 官方接口，报错认证失败。ChatOpenAI 构造时显式传 base_url=...。
模块找不到 langgraph.checkpoint.memory：旧版叫别的名字。确认 langgraph >= 0.2，必要时 uv add "langgraph>=0.2"。
langgraph-checkpoint-sqlite 没装：后续做 SQLite 持久化会报 ModuleNotFoundError。提前装好。
Windows 路径反斜杠：在 Python 字符串里写 Windows 路径要么用 r"d:\xxx" 原始字符串，要么用 \\，或直接用 /（Python 接受正斜杠）。
VSCode 选错解释器：代码补全/跳转不工作。Ctrl+Shift+P → "Python: Select Interpreter" → 选项目的 .venv。

十、小结

VSCode + Python + Pylance 是 Python 开发标配，配 Ruff 体验最佳。
核心依赖：langgraph、langchain-core、langchain-openai、langchain-community、python-dotenv、langgraph-checkpoint-sqlite。
API Key 用 .env + python-dotenv 管理，绝不硬编码、绝不提交。
.gitignore 必须忽略 .env、.venv、*.db。
项目结构按 src/ + examples/ + tests/ 组织，学习阶段可简化。
跑 test_env.py 验证一切就绪。

下一篇我们终于要写第一个 LangGraph 程序了！第一个LangGraph程序 →

开发环境搭建 ​

一、安装 VSCode 与 Python 扩展 ​

二、Jupyter 安装与用途 ​

三、安装核心依赖 ​

四、API 密钥管理 ​

五、.gitignore 模板 ​

六、项目结构建议 ​

七、验证脚本 ​

八、预期输出 ​

九、常见踩坑 ​

十、小结 ​

开发环境搭建

一、安装 VSCode 与 Python 扩展

二、Jupyter 安装与用途

三、安装核心依赖

四、API 密钥管理

五、.gitignore 模板

六、项目结构建议

七、验证脚本

八、预期输出

九、常见踩坑

十、小结