2.1 开发环境配置：装哪几层、怎么验证

2.1 开发环境配置：装哪几层、怎么验证

本节摘要：可用的 Browser-Use 环境分四层：Python 运行时、browser-use 及其依赖、浏览器内核（或本机 Chrome）、模型密钥。本节按层给出安装与验证命令，附六条高频报错的病因分析——环境问题九成出在这六处。

一个场景说明为什么分层

接到"帮我配一下环境"的需求，最怕听到的回答是"我 pip install 了一下，报错了"。报错本身就说明装到哪一层了，但很多人把四层混成一坨，报错一层、排查三层。把环境想成分层装配的命令台设备，逐层验证，出问题时立刻能定位到层——这是本节真正要教的东西，命令比命令背后的分层观次要得多。上一节说"环境没验证不接任务单"，本节就给你那张验证单。

图：环境四层装配图——每层装什么、靠什么验证

第一层与第二层：运行时和库

先确认 Python 版本，再建独立虚拟环境——为什么必须虚拟环境？browser-use 会带入一串依赖（含 Playwright 绑定），和全局包打架的概率不低，隔离是止损线。

# 第1层：确认版本，3.10 及以上
python --version          # 预期输出：Python 3.12.x 之类，低于 3.10 先升级

# 建虚拟环境并激活（Windows 下用第二行替代第三行）
python -m venv .venv
.venv\Scripts\activate    # Windows
source .venv/bin/activate # macOS 与 Linux

# 第2层：安装主库与模型接入包
pip install browser-use langchain-openai
# 预期输出：Successfully installed browser-use ... 一串包名
​

装完立刻验证引库，这一步拦截的是第 1 层遗留问题：

# 验证脚本：引库不报错，第2层就算通过
import browser_use                      # 主库
print(browser_use.__version__)          # 预期输出：0.x.x 版本号
from langchain_openai import ChatOpenAI # 模型接入包
print("imports ok")                     # 预期输出：imports ok
​

第三层：浏览器内核

browser-use 依赖 Playwright 驱动浏览器内核。两种选择：让框架用自带的 Chromium，或接管你机器上的 Chrome。第一次安装建议先把内核下载齐——不管以后走不走接管路线，内核在手，兜底方案就在。

# 第3层：下载内核（只需一次，几百 MB，网络差时耐心等）
playwright install chromium
# 预期输出：下载进度条至 100%，最后报告 chromium 已安装
​

第四层：模型密钥

密钥属于账号敏感信息，只走环境变量，不写进代码——这一习惯在第 6 章谈安全时还会升级成纪律。Windows 与 macOS 设置方式不同，注意会话关闭后环境变量会失效，长期开发要写进系统配置。

# Windows（当前会话有效）
set OPENAI_API_KEY=sk-你的密钥
# macOS 与 Linux
export OPENAI_API_KEY=sk-你的密钥
​

四层装完做冒烟测试：让模型回一个字，验证第 4 层的鉴权与网络是通的。

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o")            # 读环境变量里的密钥
reply = llm.invoke("只回复两个字：就绪")     # 最小调用，验密钥与连通
print(reply.content)                        # 预期输出：就绪
​

高频报错对照表

验收标准

别凭感觉认为"装好了"。本节验收只认三件事：引库脚本打印出版本号、内核检查通过、冒烟测试打印出"就绪"。三件都做到，第 2 章第 2 节的任务单才有资格接。

团队协作：环境也要交作业

单人开发环境随缘就行，多人协作必须把环境"交作业"——固化下来可复现。做法是版本锁定加说明文档：

# 冻结当前环境的关键包版本
pip freeze | findstr /I "browser-use playwright langchain"
# 预期输出形如：
# browser-use==0.x.y
# playwright==1.x.y
# langchain-openai==0.x.y
​

把输出的版本号写进团队的依赖清单，新同事按清单装，不用猜"上次你到底装的哪个版本"。比版本号更隐蔽的坑是浏览器内核版本：内核与 playwright 绑定有兼容矩阵，A 同学本机内核新、B 同学旧，同一份代码一个能跑一个闪退。所以清单里除了包版本，还要注明内核是"自带下载"还是"接管本机 Chrome"，走的是哪条路线。

再答一个高频问题：**要不要用最新版？**新版本修 bug 也带新 bug，而你的巡检任务讲究"每天同一姿势跑"。我的建议是生产任务锁小版本，测试环境再跟进新版——稳定压倒新鲜，这是巡检体系（5.3）的地基。

**问：能不能跳过虚拟环境直接装全局？**技术上能，代价是迟早与别的项目互相打架——browser-use 带的依赖不算少，全局环境里总有一个包会被它顶掉版本。虚拟环境两分钟的事，省下的是某天半天的排查。唯一的例外是临时试用一下就删的场景，但既然你在读教程，显然不止试用。

收尾把本节验收再压一遍：引库打印版本号、内核检查通过、冒烟测试回"就绪"，三绿即通过。若三绿全过，你本周的运气已经用完了——后面遇到问题请直接翻 6.3 的速查表，别怀疑人生。

下一节环境落地成产出：跑第一段完整任务，并逐行读懂终端里滚过的每一条日志。