众元AI学习空间

01_Windows课前基线与PythonTRAE安装手册

9分钟阅读

Windows 课前基线与 Python 3.12 / TRAE 安装手册

使用时间：W00 结束后至 W01-D01。
适用范围：Windows 10/11 64 位。
课堂基线：Python 3.12.x；学生不需要卸载电脑中已经存在的其他 Python，但必须让课程项目明确使用 3.12。

0. 先确认这台电脑能参加实操

按 Win + R，输入 winver 并回车，记录 Windows 版本。再检查：

  • 系统盘或课程盘至少预留 20 GB 可用空间；Docker 后续还会持续占用镜像空间。
  • 能打开学校允许使用的下载站点；网络受限时向教师领取已核验安装包，不从网盘陌生来源下载。
  • 知道自己是否有管理员权限。Python、Git、Node 可以按当前用户安装；首次启用 WSL 2 通常需要管理员权限。
  • Edge 或 Chrome 至少有一个能正常打开，并且按 F12 能打开开发者工具。
  • 课程文件夹不要放在系统目录、安装目录或需要管理员权限的位置；使用自己的文档盘或课程盘。

教师先收集这四项结果，不要让全班同时盲装。

1. 检查现有 Python

打开 CMD，不要在网页搜索框里输入命令。依次执行：

python -V
py -V
where python
where py

判断：

现象处理
python -V 显示 Python 3.12.x不重复安装，直接进入第 3 节
python 是 3.13/3.14，但 py -3.12 -V 成功保留多个版本；创建项目环境时明确用 py -3.12
命令跳转 Microsoft Store在 Windows“管理应用执行别名”中关闭 python.exe / python3.exe 商店别名，再新开 CMD
找不到命令按第 2 节安装
where python 出现多条先记录，不直接删除；项目最终以 .venv 中的解释器为准

PowerShell 中检查命令来源应使用：

Get-Command python -All
where.exe python

PowerShell 自带的 where 是另一个命令的别名，因此不要把 where python 原样从 CMD 搬到 PowerShell。

2. 安装 Python 3.12.10

Python 3.12 后续安全版本未必继续提供传统 Windows 安装器；本课程使用仍有官方 64 位安装器的 3.12.10，项目依赖按整个 3.12 系列兼容。

  1. 打开 Python 3.12.10 官方发布页。
  2. 找到 Files → Windows installer (64-bit)。不要下载 embeddable package、源码压缩包或 32 位安装包。
  3. 双击安装器。
  4. 在第一个界面勾选 Add python.exe to PATH。
  5. 选择 Install Now。若学校电脑由管理员管理，按学校流程请求授权，不绕过权限。
  6. 安装结束后选择 Disable path length limit（若界面提供且权限允许）。
  7. 关闭安装器，同时关闭旧 CMD 和旧 TRAE 终端。
  8. 新开 CMD，执行：
python -V
py -3.12 -V
where python
python -c "import sys; print(sys.executable); print('Python 可以运行')"
python -m pip --version

通过标准：至少 py -3.12 -V 显示 Python 3.12.x；pip 能随该解释器运行。若裸 python 仍指向别的版本，不要急着改全局 PATH，下一节用 py -3.12 创建项目环境即可。

3. 安装并首次启动 TRAE / TraeCode

  1. 打开 TRAE / TraeCode 官方下载中心。
  2. 选择与 Windows 架构匹配的安装包。绝大多数 Intel/AMD 电脑使用 x64；只有明确的 Windows on ARM 设备才选择 ARM64。
  3. 双击安装包，按当前用户完成安装。安装位置不需要与课程代码目录相同。
  4. 从开始菜单启动 TRAE。首次启动可能需要更新或登录，按页面提示由学生本人完成；教师不收集账号、短信验证码或密码。
  5. 进入能看到文件树、编辑器、终端和 AI 面板的 IDE Mode。界面名称如有调整，以“文件和终端始终可见”为准。
  6. 在自己选择的课程位置创建空文件夹：
ai-coding-camp\w01_games
  1. 在 TRAE 选择“文件 → 打开文件夹”，打开 w01_games。确认左侧文件树最顶层就是该目录，而不是整个磁盘或课程父目录。
  2. 打开 TRAE 内置终端，执行：
python -V
Get-Command python

如果 TRAE 打开前才安装 Python，必须彻底退出 TRAE 后重新启动；只关闭一个终端标签不一定会刷新应用级 PATH。

4. 创建项目自己的 .venv

在 w01_games 根目录的 TRAE 终端中执行：

py -3.12 -m venv .venv

如果 py -3.12 不可用，但 python -V 已经确认是 3.12.x，可改用：

python -m venv .venv

然后：

  1. 在 TRAE 的 Python 解释器选择器中选择当前项目的 .venv。
  2. 关闭旧终端，新开一个终端。
  3. 验收：
python -V
python -c "import sys; print(sys.executable); print(sys.prefix)"
python -m pip --version

通过标准：

  • Python 为 3.12.x；
  • sys.executable 和 sys.prefix 路径中都出现当前 w01_games\.venv；
  • pip 的位置也在同一个 .venv；
  • .gitignore 中包含 .venv/。

不要只看左侧出现 .venv 文件夹。环境“已创建”不等于 TRAE 和终端“正在使用”。

5. 跑通第一个文件

在 src 目录创建 hello.py：

print("Python 3.12 与 TRAE 已就绪")

在项目根目录执行：

python src\hello.py

再执行：

python -c "import sys; assert sys.version_info[:2] == (3, 12); print('BASELINE_OK')"

看到正常文本和 BASELINE_OK，才能记为通过。

6. 浏览器与开发者工具准备

课程不绑定必须使用 Edge 还是 Chrome，但必须有一个 Chromium 系浏览器可用。

  1. 打开浏览器。
  2. 按 F12 或 Ctrl + Shift + I。
  3. 找到 Console 与 Network 标签。
  4. 在地址栏访问 http://127.0.0.1:8000/docs；当前没有后端时出现“无法访问”是正常的，这一步只确认浏览器能访问本机地址。
  5. 若学校策略禁用开发者工具，课前联系管理员；W03 的真实联调验收离不开 Network。

7. 常见故障

python 打开 Microsoft Store

关闭 Windows 应用执行别名后新开终端；也可先用 py -3.12 明确选择解释器。

No module named pip

先确认当前解释器，再执行：

python -m ensurepip --upgrade
python -m pip --version

.venv 创建失败或目录残留

先记录完整报错。不要在环境仍被 TRAE/终端占用时反复覆盖。关闭使用它的终端，确认项目中没有需要保留的依赖证据，再由教师指导重建。

TRAE 中仍显示系统 Python

重新选择 .venv 解释器并新开终端；用 sys.executable 判断，不以状态栏文字代替真实路径。

安装/下载被拦截

只使用官方站点或由教师事先核对哈希的离线包。不要关闭组织安全软件、不要使用来历不明的“绿色版”。

8. 提交给教师的环境证据

Windows 版本：
Python 版本：
系统 Python 来源：
项目 Python 来源：
pip 来源：
TRAE 能否打开项目：是 / 否
hello.py 是否真实运行：是 / 否
浏览器 F12 / Network：可用 / 受策略限制
仍待处理的问题：

任何账号登录成功都不等于环境通过；最终证据必须包含命令输出和最小程序运行。

反向链接