Positron 教程7 --- 工作区

写在前面

Positron 是 Posit 公司开发的新一代数据科学 IDE，为 Python 和 R 语言提供了全方位数据科学支持，同时还提供了 AI 辅助功能。本系列推文为 Positron IDE 官方文档的中文笔记，软件可能随时更新，建议配合官方文档一起阅读。

官网教程：https://positron.posit.co/folder-templates.html

1 文件夹模板

New Folder from Template 功能可帮助您更快地启动新项目。当您希望避免手动设置，或确保项目从一开始就包含所有推荐的文件和设置时，请使用此功能。无需运行多个设置命令，只需进行几次选择，Positron 就会自动为您完成所有设置。如果您希望：

节省时间并避免手动设置步骤
为您的语言或框架从一个即用的环境开始

1.1 模板内容

当您使用文件夹模板时，Positron 会创建一个新的项目文件夹并配置以下项目：

环境目录 ：一个专用的环境（例如 Python 的 .venv），以便您可以在不影响其他项目的情况下安装包。
版本控制 ：一个 .git 目录和一个包含针对您语言或框架常见模式的 .gitignore 文件。
目录结构：针对您的模板类型推荐的文件夹和文件，以便您的项目从一开始就井井有条。
解释器实例：一个新的解释器会话会自动启动，随时准备运行您的代码。
编辑器：在编辑器中打开一个无标题文件，或使用您选择的解释器启动一个 notebook。

1.2 使用模板

要打开 New Folder from Template 对话框，请选择左上角的"New"下拉菜单或右上角的工作区切换器。从菜单中选择"New Folder from Template"选项以调出对话框。

您也可以通过运行命令面板中的 Workspaces: New Folder from Template... 命令来调出对话框。

设置完成后，您的项目就准备好进行开发了。您可以在当前窗口或新窗口中打开该文件夹。默认情况下，Positron 会为您选择的解释器启动一个会话。您可以在设置中自定义此行为。更多详情，请参阅解释器启动指南。

1.3 关于 Python 模板

Python 模板会创建一个带有隔离环境的项目。这可以防止包版本之间的冲突，并使您的工作更具可复现性。

您可以选择使用 pyproject.toml 文件进行高级依赖项管理。

有关环境管理器的更多信息，请参阅支持的环境管理器指南。有关 Python 解释器发现的详细信息，请参阅发现 Python 安装指南。

1.4 关于 R 模板

R 模板可帮助您创建具有正确 R 版本的项目。

您可以选择使用 renv 来实现可复现性，但这是一个高级选项。除非您熟悉 renv 并且项目需要严格的依赖项管理，否则大多数用户应保持此复选框未选中状态。

renv 是一个管理项目依赖项的 R 包。它会创建项目中 R 包的快照，并将其保存在 renv.lock 文件中。这对于需要共享项目或确保精确包版本的高级用户很有帮助。了解更多关于 renv 的信息。

2 远程 SSH

Positron 支持远程 SSH 会话。此功能允许 Positron IDE 的前端（用户界面）在一台机器上运行，而后端（文件、项目、Python 和 R 会话等）在另一台机器上运行。两台机器使用普通的安全 Shell（SSH）连接进行通信。

2.1 系统要求

远程 SSH 会话可以从 Positron 桌面应用支持的任何操作系统（包括 macOS、Linux 和 Windows）发起。但是，您要连接的系统必须运行 Linux；不支持原生的 Windows 和 macOS 远程主机。

请注意，远程 SSH 仅在桌面应用上受支持。您无法从 Posit Workbench 上的 Positron Pro 会话中使用远程 SSH。

运行远程 Positron 服务器至少需要 2 GB RAM，但对于实际的数据科学工作，远程主机上预计至少需要 4 GB 或更多 RAM。

2.2 创建连接

要创建连接，请使用 Ctrl+Shift+P 打开命令面板并输入"Remote Menu"。运行 Remote SSH: Show Remote Menu 命令。

The Remote SSH menu

从那里，运行 Connect to Host 命令。系统将提示您输入主机名和凭据。

如果您不想每次都输入主机名，可以将连接信息添加到您的用户 SSH 配置中（例如，Unix-like 系统上的 ~/.ssh/config）。然后，您将来可以使用远程资源管理器视图再次连接到该系统。使用 View: Show Remote Explorer 命令打开它。

2.3 远程会话

您可以通过 Positron 窗口左下角的小指示器来识别远程 SSH 会话。

Remote SSH Status Indicator

这些会话与"常规"Positron 桌面会话之间存在一些显著差异。

文件

在远程主机内部，资源管理器选项卡将显示来自远程主机的文件，而不是本地系统的文件。

设置

当连接到远程主机时，您会看到两个不同的"设置"；一个是本地机器的设置，另一个是应用于远程机器的设置。

扩展

大多数扩展在 Positron 的后端运行。这意味着您第一次连接到远程主机时，不会安装任何扩展。您需要在远程主机上重新安装您希望在该主机上使用的任何扩展。

与资源管理器视图一样，扩展视图将帮助您查看哪些扩展安装在本地，哪些安装在远程主机上。

终端、R 和 Python

所有终端以及您的 R 和 Python 会话都将在远程主机上运行。

端口转发

当您在 Positron 中运行 Web 应用程序（例如 Shiny 应用程序）时，Positron 会自动将远程主机上的端口映射到本地机器上的端口。

例如，请注意，在 :6868 上运行的此 Shiny 应用程序会自动在本地主机上获得一个转发的端口 6868。"端口"选项卡显示当前从远程主机转发到本地主机的端口。Positron 会在可用时尝试在两台主机上使用相同的端口。

Port Forwarding for Local Web Content

2.4 长时间运行的会话

默认情况下，当您关闭 Positron 时，Positron 将强制结束您的 R 和 Python 会话。如果您希望即使在关闭 Positron 后也让会话保持运行（例如，将数据保留在内存中或让长时间运行的计算继续），您可以使用 kernelSupervisor.shutdownTimeout 设置告诉 Positron 的内核监视器保持会话运行。

Shutdown Timeout Settings

请注意，此设置仅在重启 Positron 后生效！

恢复会话

长时间运行的会话与您使用它们的工作区相关联。当您重新打开一个包含活动会话的工作区时，如果 Positron 发现任何仍在运行的会话，它将自动重新连接到这些会话。

关闭超时详情

由于监视器在没有附加任何 UI 的情况下运行您的 R 和 Python 会话，因此它无法判断您何时完成了它们。为了防止会话无限期运行并消耗远程主机上的资源，监视器将在一段时间不活动后关闭它们。这段时间由 kernelSupervisor.shutdownTimeout 设置控制。

关闭超时永远不会中断正在忙于运行代码的内核；它只有在内核空闲且未连接到任何 Positron 窗口时才开始倒计时。

如果您只想在退出 Positron 时允许内核完成任何正在运行的计算，请使用 when idle 设置。

还有一个选项允许内核永远运行；如果您使用此选项，您的 R 和 Python 内核将永远不会退出，除非您手动终止进程或从 Positron 中关闭它们。我们通常不建议使用此选项，除非您熟悉远程主机上的进程管理，因为它可能导致资源耗尽。

2.5 工作原理与故障排除

当 Positron 第一次连接到新主机时，它会执行以下操作：

建立到主机的 SSH 连接。
形成正确的 Positron Server 二进制文件的名称和下载 URL，例如 positron-reh-linux-x64-2025.01.0-39.tar.gz。
在远程主机上，将此二进制文件下载到 ~/.positron-server 并解压。
在远程主机内启动无头 Positron Server。
从前端连接到服务器。

注意

客户端和服务器必须使用完全相同的 Positron 版本。我们为常规每月版本和每日构建版本都提供了 Positron Server 构建，因此您可以将其用于远程 SSH 会话。如果您使用新客户端版本的 Positron 连接到远程主机（例如，因为有新的每月版本可用），则会下载并解压相应新版本的 Positron Server。

两个最常见的问题是：

下载 Positron Server 二进制文件时遇到 404。当您尝试对不支持的主机类型使用远程 SSH 时会发生这种情况，例如连接到 macOS 主机。
启动 Positron Server 二进制文件时遇到错误。当您尝试对 Positron 不支持的 Linux 版本使用远程 SSH 时会发生这种情况。

有时，远程服务器上的安装可能会损坏，例如，如果下载中断。如果您在远程服务器上安装 Positron 时遇到错误，可以尝试删除远程主机上的 ~/.positron-server 目录，然后重新连接。

如果您需要使用不同的 URL 来下载 Positron Server（例如，由于网络限制使用本地副本，或者即使未自动检测到特定版本也要强制使用），您可以编辑 remoteSSH.serverDownloadUrlTemplate 设置。

Remote SSH: Server Download Url Template Setting

3 开发容器

Positron 支持开发容器的预览版。使用开发容器，您可以在临时容器内运行会话，从而完全控制执行环境，并促进可复现性和隔离性。

3.1 系统要求

macOS、Windows 和 Linux 上的 Positron Desktop 支持开发容器。但是，容器本身必须从受支持的 Linux 版本构建。您还需要一个与 Docker 兼容的容器运行时，例如 Docker Desktop 或 Podman。

请注意，您不能在已经处于远程环境（例如远程 SSH、WSL 和 Posit Workbench 上的 Positron Pro 会话）中使用开发容器。

3.2 启用

重要提示

开发容器是一项实验性功能，必须手动启用。请选择启用 dev.containers.enable 设置以开启该功能。

Dev Containers experimental setting

或者将其添加到您的 settings.json 中：

复制代码

{
    "dev.containers.enable": true
}

3.3 使用

在容器中打开文件夹

打开一个包含 .devcontainer.json 文件的文件夹。您将看到如下提示：

Reopen in Container

点击通知以在容器中重新打开。

或者，如果您已关闭或禁用通知，请使用命令 Dev Containers: Reopen in Container。

附加到正在运行的容器

Remote Explorer

打开远程资源管理器视图
展开"开发容器"部分
右键单击正在运行的容器，然后选择"附加到当前窗口"或"附加到新窗口"，或使用右侧的某个按钮

重建容器

当您对 devcontainer.json 或 Dockerfile 进行更改后：

Dev Containers: Rebuild Container - 使用缓存重建
Dev Containers: Rebuild Without Cache - 从头开始完全重建
Dev Containers: Rebuild and Reopen in Container - 重建并自动重新打开

在容器内开发

Positron 的开发容器功能使用 VS Code 中可用的命令和设置的一个子集。阅读 VS Code 关于在容器内开发的指南以获取更多信息。

3.4 限制

与 Code OSS 核心不同，VS Code 的开发容器支持不是开源的。它由一个专有的、闭源的扩展提供，并在商业许可下发布。因此，Positron 的实现是新颖的，并不具备所有相同的功能。具体来说，它具有以下限制：

Positron 不支持基于 musl 的 Linux 发行版（如 Alpine）（跟踪问题）；容器必须运行 Positron 已支持的 Linux 版本。
仅支持单容器配置（不支持 docker compose）。
没有提供用于创建或编写 devcontainer.json 文件的工具或模板。
每个项目仅支持一个容器。
不支持 Docker 卷，仅支持常规挂载。
在最近使用列表中，开发容器显示的是远程路径而不是本地路径（例如 /workspaces/foo）。
不支持 VS Code 容器自定义。
不支持 RemoteCommand。
在已经处于远程的环境中（例如远程 SSH、WSL 和 Posit Workbench）不支持容器。
当已经在容器内时，容器管理功能（查看/附加到正在运行的容器）不可用。

3.5 远程会话

一旦进入容器，您的会话行为将类似于远程 SSH 会话，就像您在容器上启动了 SSH 服务器并使用远程 SSH 连接到它一样。有关更多信息，请参阅远程 SSH。

--------------- 结束 ---------------

注：本文为个人学习笔记，仅供大家参考学习，不得用于任何商业目的。如有侵权，请联系作者删除。