1. 从零开始Windows 与 macOS 下 Python 环境搭建全流程很多人第一次接触 Python卡住的地方往往不是语法而是「装完之后命令行里敲python没反应」或者「装了一堆包项目一换就全乱套」。我自己刚开始学的时候在 Windows 上装完解释器结果pip用不了折腾了一下午才发现是安装时没勾选把 Python 加入 PATH。这类问题其实有固定套路可以避开。Python 是一门解释型语言你可以把它理解成一个「翻译官」你写的.py文件是给翻译官看的稿子翻译官逐行读、逐行执行。要让这个翻译官在你电脑上工作需要三样东西——解释器本体、包管理工具 pip、以及一个顺手的代码编辑器或 IDE。这三样配齐你就能独立跑起第一个项目。这篇札记面向刚接触 Python 的开发者聚焦 Windows 和 macOS 两个平台把解释器安装、虚拟环境创建、IDE 配置这条链路走通最后交付一个能读取本地文件的入门脚本并给出运行验证步骤。全程命令可直接复制遇到报错也有对照排查。适合谁适合还没装过 Python、或者装过但环境一团乱、想重新理一遍的人。先说一个核心概念虚拟环境。你可以把它想成「每个项目一个独立的工具箱」。项目 A 用 requests 2.0项目 B 用 requests 3.0如果都装在全局必然打架。虚拟环境让每个项目有自己的site-packages目录互不干扰。这是 Python 开发里最重要的习惯之一越早养成越好。下面按平台分步骤来。Windows 用户看 1.1 和 1.2macOS 用户看 1.3然后所有人汇合到虚拟环境和 IDE 配置。1.1 Windows 安装解释器与 PATH 配置去 python.org 下载页面选最新的稳定版比如 3.12.x的 Windows installer (64-bit)。下载完双击安装界面第一屏底部有两个复选框务必勾上「Add python.exe to PATH」再点「Install Now」。这一步是新手最容易漏的漏了之后命令行敲python会提示「不是内部或外部命令」。如果已经装完但忘了勾可以手动配。右键「此电脑」→ 属性 → 高级系统设置 → 环境变量在「用户变量」里找到 Path编辑新增两条C:\Users\你的用户名\AppData\Local\Programs\Python\Python312\ C:\Users\你的用户名\AppData\Local\Programs\Python\Python312\Scripts\注意版本号目录要和你实际安装的一致。Scripts 目录里放的是 pip、virtualenv 这些工具不加进去pip就用不了。改完关掉所有命令行窗口重新打开验证python --version pip --version正常会输出Python 3.12.x和 pip 的版本号。如果python没反应但py有反应说明系统里可能有多个版本用py -3.12指定即可。1.2 Windows 下创建并激活虚拟环境进入你想放项目的目录比如D:\code\hello-python在命令行里cd D:\code\hello-python python -m venv .venvpython -m venv是调用标准库自带的 venv 模块.venv是虚拟环境目录名前面加点表示隐藏是社区惯例。执行完目录里会多出一个.venv文件夹。激活命令 Windows 和 macOS 不一样这是高频踩坑点# Windows CMD .venv\Scripts\activate.bat # Windows PowerShell .venv\Scripts\Activate.ps1 # macOS / Linux source .venv/bin/activate激活成功后命令行提示符前面会出现(.venv)。PowerShell 如果报「无法加载文件因为在此系统上禁止运行脚本」是执行策略限制用管理员身份打开 PowerShell 执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned即可这是一条本地安全策略设置改完就能正常激活。退出虚拟环境用deactivate。记住一个原则每次开发前先激活装包前先确认提示符有(.venv)否则包会装到全局去。1.3 macOS 安装与虚拟环境macOS 自带 Python 2.7老系统或没有不建议用系统自带的。推荐用 Homebrew 装brew install python3.12装完python3 --version验证。注意 macOS 上命令是python3和pip3不是python。创建虚拟环境mkdir -p ~/code/hello-python cd ~/code/hello-python python3 -m venv .venv source .venv/bin/activate激活后提示符同样出现(.venv)此时python和pip都指向虚拟环境内的版本可以直接用。macOS 的 PATH 一般由 Homebrew 自动配好如果brew命令本身找不到需要先按 Homebrew 官网的安装脚本装好。两个平台到这里就统一了激活虚拟环境后pip install装的包只属于当前项目。接下来配 IDE。2. TaoToken 前置为后续接入大模型能力做准备学 Python 到一定阶段你大概率会想让脚本调用大模型 API比如写个自动总结本地文档的小工具。这时候就需要一个稳定的 API 接入点。TaoToken 提供的就是这样一个入口官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。为什么在环境搭建阶段就提这个因为很多新手装完 Python 后第一个「有成就感」的项目就是调 API。提前把 Key 和 Base URL 准备好后面写脚本时直接填参数就行不用临时找。你需要准备三样东西我称之为「三件套」Base URL、API Key、Model ID。Base URL 就是上面那个 API 地址API Key 在控制台里创建地址是 https://taotoken.net/console/api-keys Model ID 是你想调用的模型名称在模型列表或文档里能查到。创建 Key 的流程登录后进控制台找到 API Keys 页面点新建复制生成的字符串。这个字符串只显示一次务必存到安全的地方比如项目根目录的.env文件里并且把.env加进.gitignore千万别提交到代码仓库。如果你只是想先验证模型能不能通可以用模型对话页面直接试 https://taotoken.net/models 。想长期写代码、跑 Agent 类任务可以了解 Coding Plan https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc 。这里要强调一个安全习惯API Key 永远不要硬编码在.py文件里。正确做法是用环境变量或.env文件读取。Python 里用os.environ.get(TAOTOKEN_API_KEY)获取配合python-dotenv库加载.env。这样即使代码分享出去Key 也不会泄露。把 Key 存进环境变量的方式Windows 和 macOS 略有不同。Windows 可以在系统环境变量里新增一条TAOTOKEN_API_KEYmacOS 可以在~/.zshrc里加export TAOTOKEN_API_KEY你的key然后source ~/.zshrc。这样在任何 Python 脚本里都能读到。准备工作做完你的环境就具备了「本地开发 调用大模型」的完整能力。下面进入可复制配置环节。3. 可复制配置venv、requirements 与 IDE 设置片段这一节给你可以直接抄的配置。先建项目结构hello-python/ ├── .venv/ ├── .env ├── .gitignore ├── requirements.txt └── main.py.gitignore内容.venv/ .env __pycache__/ *.pycrequirements.txt先留空后面装包时用pip freeze requirements.txt生成。这个文件的作用是记录项目依赖别人拿到你的项目pip install -r requirements.txt就能还原一模一样的环境。.env文件内容注意不要提交TAOTOKEN_API_KEY你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用 VS Code推荐装 Python 扩展Microsoft 出品。装完后按CtrlShiftPmacOS 是CmdShiftP输入「Python: Select Interpreter」选中你项目里.venv目录下的解释器。这样 VS Code 的终端、调试、代码补全都会用这个虚拟环境。VS Code 的settings.json可以加一段让保存时自动格式化{ python.defaultInterpreterPath: ${workspaceFolder}/.venv/bin/python, editor.formatOnSave: true, python.analysis.typeCheckingMode: basic }Windows 用户把路径改成${workspaceFolder}/.venv/Scripts/python.exe。这个配置片段放在项目根目录的.vscode/settings.json里团队协作时能保证大家行为一致。如果你用 PyCharm新建项目时在「Python Interpreter」里选「Existing interpreter」指向.venv里的 python 可执行文件即可。PyCharm 会自动识别虚拟环境。再给一个pyproject.toml的最小片段现代 Python 项目越来越多用它替代 requirements.txt[project] name hello-python version 0.1.0 requires-python 3.10 dependencies [ python-dotenv, requests, ]用pip install -e .可以按这个文件安装依赖。两种方式选一种即可新手先用 requirements.txt 更直观。配置齐了下面写第一个真正能跑的脚本。4. 验证请求读取本地文件的入门脚本与运行结果写一个main.py功能是读取本地一个文本文件统计行数和字符数并打印前几行。这个脚本覆盖了文件读写、异常处理、命令行参数三个基础点。import os import sys from pathlib import Path def read_file(path: str) - str: 读取文本文件返回内容字符串。 file_path Path(path) if not file_path.exists(): raise FileNotFoundError(f文件不存在: {path}) if not file_path.is_file(): raise ValueError(f路径不是文件: {path}) return file_path.read_text(encodingutf-8) def summarize(content: str) - dict: lines content.splitlines() return { 行数: len(lines), 字符数: len(content), 前3行: lines[:3], } def main(): if len(sys.argv) 2: print(用法: python main.py 文件路径) sys.exit(1) target sys.argv[1] try: content read_file(target) except (FileNotFoundError, ValueError) as e: print(f读取失败: {e}) sys.exit(1) info summarize(content) print( 文件摘要 ) for key, value in info.items(): print(f{key}: {value}) if __name__ __main__: main()准备一个测试文件sample.txtPython 学习第一天 虚拟环境很重要 坚持每天写一点运行python main.py sample.txt预期输出 文件摘要 行数: 3 字符数: 34 前3行: [Python 学习第一天, 虚拟环境很重要, 坚持每天写一点]如果输出正常恭喜你第一个可运行项目完成了。这里用到了pathlib它比老的os.path更直观推荐新手直接用。encodingutf-8是为了避免中文在 Windows 上乱码这个参数很关键。再进一步如果你想验证 API 接入是否通可以加一个api_check.pyimport os import requests from dotenv import load_dotenv load_dotenv() api_key os.environ.get(TAOTOKEN_API_KEY) base_url os.environ.get(TAOTOKEN_BASE_URL, https://taotoken.net/api) if not api_key: raise SystemExit(未找到 TAOTOKEN_API_KEY请检查 .env 文件) resp requests.post( f{base_url}/v1/chat/completions, headers{Authorization: fBearer {api_key}}, json{ model: 你的模型ID, messages: [{role: user, content: 你好请回复一句话}], }, timeout30, ) print(resp.status_code) print(resp.json())运行前先pip install requests python-dotenv。返回 200 且 JSON 里有内容说明 Key 和 Base URL 都配对了。这一步能帮你确认「三件套」是否齐全。5. 本篇常见错排查401、local proxy failed 与 reading choices环境搭建和 API 调用过程中报错集中在几个固定位置。下面按真实报错对照排查。报错一python: command not found或「不是内部或外部命令」原因解释器没装好或 PATH 没配。Windows 检查环境变量里有没有 Python 目录和 Scripts 目录macOS 确认用python3而不是python。用where pythonWindows或which python3macOS看实际指向哪个路径。报错二pip: command not found原因Scripts 目录没进 PATH。Windows 手动加...\Python312\Scripts\macOS 用python3 -m pip代替pip更稳。其实任何平台都可以用python -m pip install xxx这样不依赖 PATH推荐。报错三401 Unauthorized调用 API 时最常见。原因通常是 Key 错了、Key 没读到、或者请求头格式不对。检查三点.env里 Key 有没有多余空格load_dotenv()有没有在读取环境变量之前调用请求头是不是Authorization: Bearer key格式。如果 Key 是从控制台复制的注意别把前后引号也复制进去。报错四local proxy failed或连接超时这类报错通常和网络环境有关。先确认base_url拼写正确是https://taotoken.net/api不要多写或少写斜杠。再检查本机是否有异常的代理设置干扰请求。用requests时可以显式设置proxies{http: None, https: None}排除本机代理干扰或者换一个网络环境重试。如果公司网络有出口限制联系网络管理员确认。报错五KeyError: choices或reading choices说明返回的 JSON 里没有choices字段通常是请求失败但代码直接取了resp.json()[choices]。正确做法是先看resp.status_code再打印完整resp.text。常见原因是 model ID 写错、请求体格式不对、或者额度不足。把resp.json()完整打印出来错误信息一般写在error字段里。报错六ModuleNotFoundError: No module named requests原因包装到了全局但当前用的是虚拟环境或者激活了虚拟环境但没在里面装包。确认提示符有(.venv)然后pip install requests。用pip list看当前环境装了哪些包。报错七中文乱码Windows 上读文件没指定encodingutf-8时容易出现。统一在read_text和open里加encodingutf-8。写文件同理。报错八PowerShell 激活脚本被禁止前面提过执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned。这是本地策略只影响当前用户安全可控。排查的核心思路是先看报错原文再定位是环境问题还是代码问题。环境问题看 PATH 和虚拟环境代码问题看异常堆栈。养成打印resp.status_code和resp.text的习惯能省很多时间。6. 继续深入把环境用起来接入文档与模型验证入口环境搭好只是起点。接下来你可以做几件事让这套环境真正产生价值。第一把常用依赖固化。每次装完包执行pip freeze requirements.txt换电脑时一条命令还原。第二给项目加个README.md写清楚怎么创建虚拟环境、怎么装依赖、怎么运行三个月后你自己回来看也能秒懂。第三把.env模板化成.env.example只留键名不留值方便分享。想验证模型能力直接去模型对话页面试 https://taotoken.net/models 。想系统接入看接入文档 https://taotoken.net/doc 。需要管理 Key去控制台 https://taotoken.net/console/api-keys 。长期写代码或跑 Agent了解 Coding Plan https://taotoken.net/coding-plan 。Claude Code 相关接入参考 https://taotoken.net/coding-plan 。最后分享一个我自己的习惯每学一个新库就在hello-python里新建一个独立脚本跑通最小示例再往项目里搬。这样环境始终干净出问题也好定位。Python 的学习曲线前期平缓把环境这关过了后面写脚本、做自动化、调 API 都是顺水推舟的事。