如何配置VSCode以正确导入Webots Python API的controller模块？

算力阿峰

2026-7-26

解决VSCode中Webots Python API导入报错No module named 'controller'的问题

你遇到的核心问题是VSCode的Python解释器找不到Webots自带的controller模块路径，以下是几种直接可行的解决方法：

方法一：配置VSCode全局Python分析路径

打开VSCode，按下Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS），输入Preferences: Open Settings (JSON)并回车，打开settings.json配置文件。

在文件中添加以下配置，把路径替换成你本地Webots安装目录下的Python API路径：

{
  "python.analysis.extraPaths": [
    // Windows示例路径
    "C:/Program Files/Webots/lib/controller/python",
    // macOS示例路径
    // "/Applications/Webots/lib/controller/python",
    // Linux示例路径
    // "/usr/local/webots/lib/controller/python"
  ]
}

保存文件后重启VSCode，配置即可生效。

方法二：在代码中临时添加模块路径（应急方案）

如果不想修改全局配置，可在代码最开头手动把Webots的API路径加入Python的搜索路径：

import sys
# 替换为你的Webots Python API实际路径
sys.path.append("C:/Program Files/Webots/lib/controller/python")

from controller import Robot, DistanceSensor, Motor

# 后续代码保持不变
...

方法三：针对Python虚拟环境的配置

如果你使用虚拟环境开发，可通过以下方式让虚拟环境识别Webots模块：

激活你的Python虚拟环境。
找到虚拟环境目录下的site-packages文件夹（比如venv/Lib/site-packages）。
在该文件夹中新建一个名为webots.pth的文件，文件内仅写入Webots Python API的绝对路径：
```
C:\Program Files\Webots\lib\controller\python
```
保存文件后，虚拟环境的Python解释器就能自动加载controller模块。