TensorFlow 2.10.0 与 gym==0.25.2 是最稳定的组合；gym 0.26+ 改为五元组返回值，未适配会导致解包错误；GPU 推荐用 tensorflow==2.10.0（内置 CUDA 11.2）；PPO/A2C 中 advantage 必须用 tf.stop_gradient() 切断梯度。
tensorflow 和 gym 的版本兼容性是环境搭起来的第一道坎，不是装上就能跑。TensorFlow 2.x（如 2.10.0）配 gym==0.25.2 是当前最稳的组合；用 gymnasium 虽然新，但很多 RL 框架（比如 deep-rl-tensorflow）还没适配，硬切会卡在 env.reset() 返回值结构上。
pip install 时必须锁定 gym 版本
直接 pip install gym 会装最新版（0.26+），它把 env.step() 的返回从四元组改成五元组：(next_obs, reward, done, info) → (next_obs, reward, terminated, truncated, info)。TensorFlow 的 RL 代码如果没显式处理 terminated 和 truncated，就会报 ValueError: not enough values to unpack。
- 正确命令：
pip install gym[atari]==0.25.2 gym[accept-rom-license] - Apple Silicon 用户额外加：
pip install pygame --no-binary pygame（否则atari-py编译失败） - Windows 上若提示
SDL2.dll not found，手动下载 SDL2 并放入 PythonScripts目录
GPU 支持要分清 tensorflow-gpu 还是 tensorflow
TensorFlow 2.10 是最后一个自带 GPU 支持的版本；2.11+ 已移除 CUDA 集成，改用 tensorflow-cpu + 单独安装 tf-keras + cuda-python 组合——太折腾，不推荐。所以：
- 想用 GPU：老老实实装
tensorflow==2.10.0（它内置 CUDA 11.2 支持） - 别碰
tensorflow-gpu包——这个包在 2.0+ 已废弃，装了反而冲突 -
tf.config.list_physical_devices('GPU')返回空列表？先检查nvidia-smi是否可见，再确认 CUDA 驱动版本 ≥ 11.2
Deep RL 项目里 main.py 的参数不能乱传
像 deep-rl-tensorflow 这类项目，--network_header_type 和 --network_output_type 是强耦合的。比如设 --network_output_type=dueling 却没配 --network_header_type=nature，模型构建时会因卷积头输出 shape 不匹配而崩在 tf.keras.Model 初始化阶段，报错信息是 InvalidArgumentError: Incompatible shapes。
立即学习“Python免费学习笔记（深入）”；
- 常见合法组合：
--network_header_type=mlp --network_output_type=vanilla（全连接基础 DQN） -
--network_header_type=nature --network_output_type=dueling（Atari 标准配置） -
--env_name必须是gym.make()真正注册的名字，FrozenLake-v1和FrozenLake8x8-v0是两个不同环境，不能拼错
Actor-Critic 双头网络最容易漏掉 stop_gradient
写 PPO 或 A2C 时，advantage = reward + gamma * next_value - value 这个张量如果直接参与 actor_loss 计算，梯度会反传进 Critic 网络，导致策略更新震荡。必须用 tf.stop_gradient(advantage) 切断这条路径——这不是可选项，是数学要求。
- 错误写法：
actor_loss = -tf.reduce_mean(log_prob * advantage)（advantage 未 stop） - 正确写法：
advantage = tf.stop_gradient(reward + gamma * next_value - value) - 顺带一提：
critic_loss用tf.keras.losses.MSE，但 target 要是reward + gamma * next_value，不是reward单独一个数
环境能 import 成功、gym.make 不报错、env.reset() 返回正确 shape，只是万里长征第一步。真正卡住人的，永远是 advantage 没 stop_gradient、gym 版本跳变导致的 tuple unpack 错误、或者双头网络里 logits 和 value 共享了最后一层权重——这些坑不在文档里，只在你第一次 python main.py 报错的 traceback 最底下。
