编辑器配置

编辑器配置#

编辑器配置是可选步骤，运行 Isaac Lab 无需配置编辑器。仓库提供了 Visual Studio Code 及 Cursor 等兼容编辑器的共享设置。配置前，先完成一种 Isaac Lab 安装方式 。

.vscode 目录包含已纳入版本控制的模板和任务：

.vscode
├── tools
│   ├── launch.template.json
│   └── settings.template.json
├── extensions.json
├── launch.json  # generated by isaaclab --editor
├── settings.json  # generated by isaaclab --editor
└── tasks.json

配置源码检出目录#

在编辑器中打开 Isaac Lab 仓库根目录，再从该目录的终端运行与你的安装方式对应的配置命令。

默认 Newton 环境使用：

uv run isaaclab --editor

如果通过 isaacsim 可选依赖组使用 Isaac Sim，需包含该依赖组，使配置命令能发现其扩展：

uv run --extra isaacsim isaaclab --editor

激活已安装 Isaac Lab 的 uv、venv 或 conda 环境，再运行：

isaaclab --editor

完成 下载软件包安装 后，通过 Isaac Lab 启动器运行配置命令：

./isaaclab.sh --editor

isaaclab.bat --editor

命令面板中的 setup_python_env 任务采用推荐的 uv 工作流。

该命令创建或更新以下本机文件：

  • .vscode/launch.json ：调试配置。已有文件会保留。

  • .vscode/settings.json ：解释器及共享编辑器设置。

  • pyrightconfig.json ：兼容 Pyright 的语言服务器所需导入路径。

不同机器的解释器和扩展路径不同，因此生成文件由 Git 忽略。更换 Python 环境或 Isaac Sim 安装后，应重新运行命令。如果未安装 Isaac Sim，命令会打印警告，但仍会配置本地 Isaac Lab 包。

pyproject.toml 中已纳入版本控制的 [tool.pyright] 表，使克隆后即可解析 source 下的包。生成的 pyrightconfig.json 继承该配置，并添加 Isaac Sim 扩展以及当前 Python 环境中的 Isaac Lab 包。这覆盖源码、可编辑和 wheel 安装，无需将绝对路径存入 Git。

配置 VS Code#

VS Code 提示时，安装仓库推荐的扩展，至少安装 Python 和 Pylance。运行上述配置命令后，通过命令面板的 Python: Select Interpreter 选择执行该命令的同一解释器。推荐的 uv 安装在 Linux 下对应 .venv/bin/python ，在 Windows 下对应 .venv\Scripts\python.exe 。

配置 Cursor#

Cursor 无法使用 Pylance，因为 Pylance 的许可仅允许官方 VS Code 构建使用。请安装 Python 扩展和 basedpyright 扩展（ detachhead.basedpyright ），然后：

  1. 根据安装方式运行上面的同一配置命令。

  2. 选择运行该命令的解释器。

  3. 重新加载 Cursor 窗口，让 basedpyright 重新读取 pyrightconfig.json 。

无需 Cursor 专用路径列表。Pylance 和 basedpyright 读取同一份 Pyright 配置。

排查编辑器导入问题#

如果某个导入仍无法解析：

  1. 确认编辑器所选解释器与配置命令中的 python 一致。

  2. 如果缺少的导入来自 omni 、 pxr 或 isaacsim ，使用 uv run --extra isaacsim isaaclab --editor 重新配置。

  3. 重新加载编辑器窗口。

  4. 检查根目录 pyrightconfig.json 中生成的 extraPaths 。

如果语言服务器索引占用过多内存，移除项目未使用的仿真器扩展目录。

Isaac Sim 对 VS Code 的支持，更多信息见：

附加到正在运行的 debugpy 会话#

生成的 .vscode/launch.json 包含 Python: Debugger Attach 配置，通过 localhost:3000 端口连接 debugpy 会话。

使用步骤：

  1. 设置断点。

  2. 按以下方式通过 debugpy 运行代码：

    uv run python -m debugpy --listen 3000 --wait-for-client -c "from isaaclab.cli import cli; cli()" [cli_args]

    ./isaaclab.sh -p -m debugpy --listen 3000 --wait-for-client -c "from isaaclab.cli import cli; cli()" [cli_args]

  3. 在 VS Code 的运行和调试面板中选择 Python: Debugger Attach ，点击绿色运行按钮或按 F5 。VS Code 会连接运行于 localhost:3000 的 debugpy 服务器。

配置 Python 解释器#

配置命令会将执行它的解释器记录在 .vscode/settings.json 中。例如，Linux 上的 uv 源码检出目录使用：

{
   "python.defaultInterpreterPath": "/path/to/IsaacLab/.venv/bin/python",
}

编辑器中的选择优先于此默认值。更换环境后，应重新配置，并通过状态栏或命令面板的 Python: Select Interpreter 选择新解释器。

生成的启动配置始终运行所记录的解释器。VS Code 会将 _isaac_sim/python.sh 等包装脚本解析为底层 Python 可执行文件，跳过 Isaac Sim 必需的环境设置。如果 .vscode/launch.json 已存在，配置过程会保留它；请向每个配置添加 "python": "${config:python.defaultInterpreterPath}" ，或删除文件后重新运行配置命令生成。

选择 Python 解释器的更多信息见 VS Code 文档 。

设置格式化和代码检查#

我们使用 ruff 作为格式化工具和代码检查工具。这些在 .vscode/settings.json 文件中进行配置：

{
   "ruff.configuration": "${workspaceFolder}/pyproject.toml",
}

ruff 代码检查工具将在您的代码中显示警告和错误，以帮助您遵循 Python 最佳实践和项目的编码标准。

目录