新版Gym（0.26+）已将MuJoCo等商业环境移出，需改用gymnasium或独立包；确认版本后，推荐切换至gymnasium以支持HalfCheetah-v4等环境。
强化学习入门，环境交互是第一道坎。好多新手刚装上Gym，跑个经典的CartPole还没问题，一换到HalfCheetah就炸出一堆报错。别急，下面这几个坑几乎人人都会踩，翻出来说说怎么填。
gym.make() 创建环境时为什么报错 “No module named 'gym.envs.mujoco'”
这不是你环境没装对，而是新版 Gym（0.26+）把 MuJoCo 等商业仿真环境拆到了 gymnasium 生态或独立包里。Gym 本身现在只保留经典控制、Atari（需额外安装）、toy_text 等免许可环境。
实操建议：
- 确认你用的是
gym还是gymnasium：运行import gym; print(gym.__version__)，若 ≥0.26 且想用HalfCheetah-v4这类环境，直接切到gymnasium（推荐，官方维护更活跃） - 若坚持用旧版 Gym（pip install gym==0.25.2），再装
gym[mujoco]（需本地有 MuJoCo license） - 快速验证是否可用：用
gym.make("CartPole-v1")—— 这个环境永远内置，不依赖额外模块
step() 返回的 reward 总是 0 或 nan，怎么查源头
reward 不合理，90% 情况不是算法问题，而是环境内部逻辑或 step 调用方式不对。尤其注意：某些环境（如 MountainCar-v0）只在到达目标时给 +1，其余全为 0；而 Acrobot-v1 是每步 -1，靠“少扣分”来学习。
实操建议：
- 先看文档：访问 https://www.gymlibrary.dev，搜索你用的环境名，点开 “Reward” 小节——那里写明了数学定义
- 手动单步调试：在
env.step(action)后立刻打印reward和done，观察是否在done=True前 reward 长期为 0 - 检查 action 是否越界：
env.action_space.sample()查合法范围，传入非法值可能导致 reward 返回nan（尤其连续动作空间用np.random.randn()直接传）
reset() 后 observation 形状突变，导致模型输入报错
Gym 环境的 observation_space 是契约，但部分老环境（如早期 Atari wrapper）在 reset() 时可能返回未归一化的 uint8 图像，而 step() 返回 float32；也有环境在不同 episode 长度下 padding 方式不一致。
实操建议：
- 每次
reset()后立刻检查：obs = env.reset(); print(obs.shape, obs.dtype)，别假设它和上一次一样 - 统一预处理：用
gym.wrappers.TransformObservation或手动加obs.astype(np.float32) / 255.0（图像）或np.clip(obs, -10, 10)（防止 inf） - 避免用
env.observation_space.shape直接做网络输入层尺寸——有些 space 是Dict或Box(low=-inf, high=inf)，得用env.observation_space.sample().shape实测
用 render() 可视化时黑屏或报 “module 'pygame' has no attribute 'display'”
新版 Gym/Gymnasium 默认用 rgb_array 模式（返回 numpy 数组），不启动图形界面；而 human 模式依赖 pygame 或 glfw，但很多服务器/conda 环境没装 GUI 支持库。
实操建议：
- 先试非 GUI 模式：
env.render(mode="rgb_array")，返回(H,W,3)数组，用plt.imshow()显示，绕过所有渲染后端问题 - 要真窗口，Linux 用户确保已装
sudo apt-get install python3-opengl libgl1-mesa-glx；Mac 用户用brew install sdl2；Windows 用户优先用gymnasium+pygame组合 - 关键细节：
render()必须在reset()之后、step()循环中调用，且不能在done=True后继续调用——否则 pygame 状态错乱，黑屏或崩溃
说到底，reward 的符号、scale、稀疏性，比算法选择更早决定训练成败；而 gym.make() 和 step() 的返回契约，必须亲手 print() 验证，不能信文档或示例代码里的“理所当然”。动手试一下，比看十篇教程都管用。
