跳至主要内容

在 Codespace 中转发端口

您可以在 Codespace 中转发端口,以测试和调试您的应用程序。您还可以管理端口协议,并在组织内或公开共享端口。

说明

  • 将 GitHub Codespaces 与 JetBrains IDE 配合使用目前处于公开测试阶段,可能会发生更改。
  • 要在 JetBrains IDE 中处理 Codespace,您必须使用 JetBrains Gateway 的 2023.3.* 或 2024.1.* 版本。

关于已转发的端口

端口转发使您可以访问 Codespace 内运行的 TCP 端口。例如,如果您在 Codespace 中的特定端口上运行 Web 应用程序,则可以转发该端口。这使您可以从本地计算机上的浏览器访问该应用程序,以便进行测试和调试。

当 Codespace 内运行的应用程序将输出打印到包含 localhost URL(例如 https://127.0.0.1:PORThttp://127.0.0.1:PORT)的终端时,该端口会自动转发。如果您在浏览器或 Visual Studio Code 中使用 GitHub Codespaces,则终端中的 URL 字符串会转换为一个链接,您可以单击该链接以在本地计算机上查看网页。默认情况下,GitHub Codespaces 使用 HTTP 转发端口。

您可以编辑存储库的开发容器配置,以自动转发一个或多个端口。您还可以手动转发端口、标记已转发的端口、与组织成员共享已转发的端口、公开共享已转发的端口,以及将已转发的端口添加到 Codespace 配置中。

注意:组织所有者可以限制公开或在组织内提供转发端口的能力。有关详细信息,请参阅“限制转发端口的可见性”。

转发端口

您可以手动转发未自动转发的端口。

  1. 在 Codespace 中打开终端。

  2. 单击“端口”选项卡。

  3. 在端口列表下方,单击“添加端口”。

    Screenshot of the "Add port" button.

  4. 键入端口号或地址,然后按 Enter。

    Screenshot of the number 3000 being entered into the port number field for a new forwarded port.

使用 HTTPS 转发

默认情况下,GitHub Codespaces 使用 HTTP 转发端口,但您可以根据需要更新任何端口以使用 HTTPS。如果您更新具有公共可见性的端口以使用 HTTPS,则端口的可见性将自动更改为私有。

  1. 在 Codespace 中打开终端。

  2. 单击“端口”选项卡。

  3. 右键单击要更新的端口,然后将鼠标悬停在“更改端口协议”上。

    Screenshot of the pop-up menu for a forwarded port, with the "Change Port Protocol" option selected and "HTTPS" selected in the submenu.

  4. 选择此端口所需的协议。您选择的协议将在此端口上保存 Codespace 的整个生命周期。

共享端口

注意:只有当您的组织使用 GitHub Team 或 GitHub Enterprise Cloud 时,您才能将端口设为对组织私有。

如果您想与他人共享已转发的端口,您可以将端口设为对组织私有,也可以将端口设为公开。在您将端口设为对组织私有后,组织中任何拥有端口 URL 的人都可以查看正在运行的应用程序。在您将端口设为公开后,任何知道 URL 和端口号的人都可以查看正在运行的应用程序,而无需进行身份验证。

注意:您对端口可见性选项的选择可能受到为您的组织配置的策略的限制。有关详细信息,请参阅“限制转发端口的可见性”。

  1. 在 Codespace 中打开终端。

  2. 单击“端口”选项卡。

  3. 右键单击要共享的端口,单击“端口可见性”,然后单击“对组织私有”或“公开”。

    Screenshot of the pop-up menu for a forwarded port, with the "Port Visibility" option selected and "Private" selected in the submenu.

  4. 单击端口的本地地址右侧的复制图标。

    Screenshot of the "Ports" panel. The copy icon, which copies a forwarded port's URL, is highlighted with an orange outline.

  5. 将复制的 URL 发送给您要与之共享端口的人员。

使用命令行工具和 REST 客户端访问端口

当您转发端口时,您的应用程序将通过 URL https://CODESPACENAME-PORT.app.github.dev 提供。例如,https://monalisa-hot-potato-vrpqrxxrx7x2rxx-4000.app.github.dev。如果您从 VS Code 桌面应用程序转发私有端口,您的应用程序还将通过 localhost 端口(例如 127.0.0.1:4000)提供。

要使用 REST 客户端(例如 Postman)或命令行工具(例如 curl)访问您的应用程序,如果您使用的是 localhost 端口,或者您正在访问远程域中的公共端口,则无需进行身份验证。但是,要连接到远程域中的私有端口,您必须使用请求中的 GITHUB_TOKEN 访问令牌进行身份验证。

注意:当您启动代码空间时,GITHUB_TOKEN 会自动创建,并且在代码空间会话期间保持不变。如果您停止然后重新启动代码空间,将生成新的 GITHUB_TOKEN

查找要连接到的地址

  1. 在 Codespace 中打开终端。

  2. 单击端口选项卡。这将列出您已转发的所有端口。

  3. 右键单击您要连接到的端口,然后单击复制本地地址

    Screenshot of the pop-up menu for a forwarded port with the "Copy Local Address" option highlighted with an orange outline.

  4. 将复制的地址粘贴到某处以供以后使用。

查找 GITHUB_TOKEN

  1. 在代码空间的终端中,输入 echo $GITHUB_TOKEN

    令牌是一个以 ghu_ 开头的字符串。

  2. 复制令牌。

    重要:不要与任何人共享此访问令牌。

使用 curl 访问已转发的端口

在本地计算机的终端中,输入

curl ADDRESS -H "X-Github-Token: TOKEN"

ADDRESSTOKEN 替换为之前复制的值。

使用 Postman 访问已转发的端口

  1. 打开 Postman。

  2. 创建新的 GET 请求。

  3. 将您之前复制的地址粘贴为请求 URL。

    Screenshot of the URL for the forwarded port, pasted into Postman as the GET request URL. The URL is highlighted.

  4. 标头选项卡中,创建一个新条目,其中键为“X-Github-Token”,值为之前复制的 GITHUB_TOKEN

    Screenshot of a dummy GITHUB_TOKEN, pasted into Postman as the value of the X-GitHub-Token key. The key and value are highlighted.

  5. 单击发送

自动转发端口

你可以将一个转发端口添加到存储库的 GitHub Codespaces 配置中,以便为从存储库创建的所有 Codespaces 自动转发该端口。更新配置后,必须重新构建任何以前创建的 Codespaces,才能应用更改。有关开发容器配置文件的更多信息,请参阅“开发容器简介”。

  1. 在你的 Codespaces 中,打开要更新的开发容器配置文件。通常,此文件是 .devcontainer/devcontainer.json

  2. 添加 forwardPorts 属性。

    "forwardPorts": [NUMBER],
    

    NUMBER 替换为你想要转发的端口号。这可以是端口号的逗号分隔列表。

  3. 保存文件。

标记端口

在浏览器或 VS Code 桌面应用程序中打开 Codespaces 时,你可以标记一个转发端口,以便在列表中更轻松地识别它。

  1. 在 Codespace 中打开终端。

  2. 单击“端口”选项卡。

  3. 右键单击要标记的端口,然后单击设置端口标签

    Screenshot of the pop-up menu for a forwarded port, with the "Set Port Label" option highlighted with an orange outline.

  4. 为你的端口键入一个标签,然后按 Enter。

    Screenshot of the label "Staging" added as a custom label for a forwarded port.

自动标记转发端口

你可以标记一个端口,并将更改写入存储库的开发容器配置文件。如果你对使用 forwardPorts 属性自动转发的端口执行此操作,那么该标签将自动应用于从使用该配置文件的存储库创建的所有未来 Codespaces 的该转发端口。

  1. 在 Codespace 中打开终端。

  2. 单击“端口”选项卡。

  3. 右键单击要将标签属性添加到 Codespaces 配置的端口,然后单击设置标签并更新 devcontainer.json

    Screenshot of the pop-up menu for a forwarded port, with the "Set Label and Update devcontainer.json" option highlighted with an orange outline.

  4. 为你的端口键入一个标签,然后按 Enter。

    Screenshot of the label "Staging" added as a custom label for a forwarded port.

  5. 如果你的存储库有多个开发容器配置文件,系统会提示你选择要更新的文件。

    开发容器配置文件已更新,以便在 portsAttributes 属性中包含新标签。例如

    // Use 'forwardPorts' to make a list of ports inside the container available locally.
    "forwardPorts": [3333, 4444],
    
    "portsAttributes": {
      "3333": {
        "label": "app-standard-preview"
      },
      "4444": {
        "label": "app-pro-preview"
      }
    }
    

当 Codespace 内运行的应用程序将输出打印到包含 localhost URL(例如 https://127.0.0.1:PORThttp://127.0.0.1:PORT)的终端时,该端口会自动转发。如果您在浏览器或 Visual Studio Code 中使用 GitHub Codespaces,则终端中的 URL 字符串会转换为一个链接,您可以单击该链接以在本地计算机上查看网页。默认情况下,GitHub Codespaces 使用 HTTP 转发端口。

您可以编辑存储库的开发容器配置,以自动转发一个或多个端口。您还可以手动转发端口、标记已转发的端口、与组织成员共享已转发的端口、公开共享已转发的端口,以及将已转发的端口添加到 Codespace 配置中。

注意:组织所有者可以限制公开或在组织内提供转发端口的能力。有关详细信息,请参阅“限制转发端口的可见性”。

转发端口

您可以手动转发未自动转发的端口。

  1. 在 Codespace 中打开终端。

  2. 单击“端口”选项卡。

  3. 在端口列表下方,单击“添加端口”。

    Screenshot of the "Add port" button.

  4. 键入端口号或地址,然后按 Enter。

    Screenshot of the number 3000 being entered into the port number field for a new forwarded port.

共享端口

注意:只有当您的组织使用 GitHub Team 或 GitHub Enterprise Cloud 时,您才能将端口设为对组织私有。

如果您想与他人共享已转发的端口,您可以将端口设为对组织私有,也可以将端口设为公开。在您将端口设为对组织私有后,组织中任何拥有端口 URL 的人都可以查看正在运行的应用程序。在您将端口设为公开后,任何知道 URL 和端口号的人都可以查看正在运行的应用程序,而无需进行身份验证。

注意:您对端口可见性选项的选择可能受到为您的组织配置的策略的限制。有关详细信息,请参阅“限制转发端口的可见性”。

  1. 在 Codespace 中打开终端。

  2. 单击“端口”选项卡。

  3. 右键单击要共享的端口,单击端口可见性,然后单击仅限于组织公开

    Screenshot of the pop-up menu for a forwarded port, with the "Port Visibility" option selected and "Private" selected in the submenu.

  4. 单击端口的本地地址右侧的复制图标。

    Screenshot of the "Ports" panel. The copy icon, which copies a forwarded port's URL, is highlighted with an orange outline.

  5. 将复制的 URL 发送给您要与之共享端口的人员。

使用命令行工具和 REST 客户端访问端口

当您转发端口时,您的应用程序将通过 URL https://CODESPACENAME-PORT.app.github.dev 提供。例如,https://monalisa-hot-potato-vrpqrxxrx7x2rxx-4000.app.github.dev。如果您从 VS Code 桌面应用程序转发私有端口,您的应用程序还将通过 localhost 端口(例如 127.0.0.1:4000)提供。

要使用 REST 客户端(例如 Postman)或命令行工具(例如 curl)访问您的应用程序,如果您使用的是 localhost 端口,或者您正在访问远程域中的公共端口,则无需进行身份验证。但是,要连接到远程域中的私有端口,您必须使用请求中的 GITHUB_TOKEN 访问令牌进行身份验证。

注意:当您启动代码空间时,GITHUB_TOKEN 会自动创建,并且在代码空间会话期间保持不变。如果您停止然后重新启动代码空间,将生成新的 GITHUB_TOKEN

查找要连接到的地址

  1. 在 Codespace 中打开终端。

  2. 单击端口选项卡。这将列出您已转发的所有端口。

  3. 右键单击您要连接到的端口,然后单击复制本地地址

    Screenshot of the pop-up menu for a forwarded port with the "Copy Local Address" option highlighted with an orange outline.

  4. 将复制的地址粘贴到某处以供以后使用。

查找 GITHUB_TOKEN

  1. 在代码空间的终端中,输入 echo $GITHUB_TOKEN

    令牌是一个以 ghu_ 开头的字符串。

  2. 复制令牌。

    重要:不要与任何人共享此访问令牌。

使用 curl 访问已转发的端口

在本地计算机的终端中,输入

curl ADDRESS -H "X-Github-Token: TOKEN"

ADDRESSTOKEN 替换为之前复制的值。

使用 Postman 访问已转发的端口

  1. 打开 Postman。

  2. 创建新的 GET 请求。

  3. 将您之前复制的地址粘贴为请求 URL。

    Screenshot of the URL for the forwarded port, pasted into Postman as the GET request URL. The URL is highlighted.

  4. 标头选项卡中,创建一个新条目,其中键为“X-Github-Token”,值为之前复制的 GITHUB_TOKEN

    Screenshot of a dummy GITHUB_TOKEN, pasted into Postman as the value of the X-GitHub-Token key. The key and value are highlighted.

  5. 单击发送

自动转发端口

你可以将一个转发端口添加到存储库的 GitHub Codespaces 配置中,以便为从存储库创建的所有 Codespaces 自动转发该端口。更新配置后,必须重新构建任何以前创建的 Codespaces,才能应用更改。有关开发容器配置文件的更多信息,请参阅“开发容器简介”。

  1. 在你的 Codespaces 中,打开要更新的开发容器配置文件。通常,此文件是 .devcontainer/devcontainer.json

  2. 添加 forwardPorts 属性。

    "forwardPorts": [NUMBER],
    

    NUMBER 替换为你想要转发的端口号。这可以是端口号的逗号分隔列表。

  3. 保存文件。

标记端口

在浏览器或 VS Code 桌面应用程序中打开 Codespaces 时,你可以标记一个转发端口,以便在列表中更轻松地识别它。

  1. 在 Codespace 中打开终端。

  2. 单击“端口”选项卡。

  3. 右键单击要标记的端口,然后单击设置端口标签

    Screenshot of the pop-up menu for a forwarded port, with the "Set Port Label" option highlighted with an orange outline.

  4. 为你的端口键入一个标签,然后按 Enter。

    Screenshot of the label "Staging" added as a custom label for a forwarded port.

自动标记转发端口

你可以标记一个端口,并将更改写入存储库的开发容器配置文件。如果你对使用 forwardPorts 属性自动转发的端口执行此操作,那么该标签将自动应用于从使用该配置文件的存储库创建的所有未来 Codespaces 的该转发端口。

  1. 在 Codespace 中打开终端。

  2. 单击“端口”选项卡。

  3. 右键单击要将标签属性添加到 Codespaces 配置的端口,然后单击设置标签并更新 devcontainer.json

    Screenshot of the pop-up menu for a forwarded port, with the "Set Label and Update devcontainer.json" option highlighted with an orange outline.

  4. 为你的端口键入一个标签,然后按 Enter。

    Screenshot of the label "Staging" added as a custom label for a forwarded port.

  5. 如果你的存储库有多个开发容器配置文件,系统会提示你选择要更新的文件。

    开发容器配置文件已更新,以便在 portsAttributes 属性中包含新标签。例如

    // Use 'forwardPorts' to make a list of ports inside the container available locally.
    "forwardPorts": [3333, 4444],
    
    "portsAttributes": {
      "3333": {
        "label": "app-standard-preview"
      },
      "4444": {
        "label": "app-pro-preview"
      }
    }
    

如需详细了解 GitHub CLI,请参阅“关于 GitHub CLI”。

要转发端口,请使用 gh codespace ports forward 子命令。将 codespace-port:local-port 替换为要连接的远程和本地端口。输入命令后,从显示的代码空间列表中进行选择。

gh codespace ports forward CODESPACE-PORT:LOCAL-PORT

有关此命令的更多信息,请参阅 GitHub CLI 手册

要查看已转发端口的详细信息,请输入 gh codespace ports,然后选择一个代码空间。

共享端口

注意:只有当您的组织使用 GitHub Team 或 GitHub Enterprise Cloud 时,您才能将端口设为对组织私有。

如果您想与他人共享已转发的端口,您可以将端口设为对组织私有,也可以将端口设为公开。在您将端口设为对组织私有后,组织中任何拥有端口 URL 的人都可以查看正在运行的应用程序。在您将端口设为公开后,任何知道 URL 和端口号的人都可以查看正在运行的应用程序,而无需进行身份验证。

注意:您对端口可见性选项的选择可能受到为您的组织配置的策略的限制。有关详细信息,请参阅“限制转发端口的可见性”。

要更改已转发端口的可见性,请使用 gh codespace ports visibility 子命令。有三种可见性设置

  • private - 仅对您可见。这是转发端口时的默认设置。
  • org - 对拥有该存储库的组织的成员可见。
  • public - 对知道 URL 和端口号的任何人都可见。

codespace-port 替换为已转发的端口号。将 setting 替换为 privateorgpublic。输入命令后,从显示的代码空间列表中进行选择。

gh codespace ports visibility CODESPACE-PORT:SETTINGS

您可以使用一个命令设置多个端口的可见性。例如

gh codespace ports visibility 80:private 3000:public 3306:org

有关此命令的更多信息,请参阅 GitHub CLI 手册

使用命令行工具和 REST 客户端访问端口

当您转发端口时,您的应用程序将通过 URL https://CODESPACENAME-PORT.app.github.dev 提供。例如,https://monalisa-hot-potato-vrpqrxxrx7x2rxx-4000.app.github.dev。如果您从 VS Code 桌面应用程序转发私有端口,您的应用程序还将通过 localhost 端口(例如 127.0.0.1:4000)提供。

要使用 REST 客户端(例如 Postman)或命令行工具(例如 curl)访问您的应用程序,如果您使用的是 localhost 端口,或者您正在访问远程域中的公共端口,则无需进行身份验证。但是,要连接到远程域中的私有端口,您必须使用请求中的 GITHUB_TOKEN 访问令牌进行身份验证。

注意:当您启动代码空间时,GITHUB_TOKEN 会自动创建,并且在代码空间会话期间保持不变。如果您停止然后重新启动代码空间,将生成新的 GITHUB_TOKEN

查找要连接到的地址

要查找已转发端口的地址,请输入 gh codespace ports。如果您有多个代码空间,请从显示的列表中选择相应的代码空间。

复制地址并将其粘贴到某处以供以后使用。

查找 GITHUB_TOKEN

  1. 为您的代码空间启动 SSH 会话。

    gh codespace ssh
    
  2. 如果您有多个代码空间,请从显示的列表中选择相应的代码空间。

  3. 显示 GITHUB_TOKEN

    echo $GITHUB_TOKEN
    

    令牌是一个以 ghu_ 开头的字符串。

  4. 复制令牌。

    重要:不要与任何人共享此访问令牌。

  5. 退出 SSH 会话。

    exit
    

使用 curl 访问已转发的端口

在本地计算机的终端中,输入

curl ADDRESS -H "X-Github-Token: TOKEN"

ADDRESSTOKEN 替换为之前复制的值。

使用 Postman 访问已转发的端口

  1. 打开 Postman。

  2. 创建新的 GET 请求。

  3. 将您之前复制的地址粘贴为请求 URL。

    Screenshot of the URL for the forwarded port, pasted into Postman as the GET request URL. The URL is highlighted.

  4. 标头选项卡中,创建一个新条目,其中键为“X-Github-Token”,值为之前复制的 GITHUB_TOKEN

    Screenshot of a dummy GITHUB_TOKEN, pasted into Postman as the value of the X-GitHub-Token key. The key and value are highlighted.

  5. 单击发送

自动转发端口

你可以将一个转发端口添加到存储库的 GitHub Codespaces 配置中,以便为从存储库创建的所有 Codespaces 自动转发该端口。更新配置后,必须重新构建任何以前创建的 Codespaces,才能应用更改。有关开发容器配置文件的更多信息,请参阅“开发容器简介”。

  1. 在你的 Codespaces 中,打开要更新的开发容器配置文件。通常,此文件是 .devcontainer/devcontainer.json

  2. 添加 forwardPorts 属性。

    "forwardPorts": [NUMBER],
    

    NUMBER 替换为你想要转发的端口号。这可以是端口号的逗号分隔列表。

  3. 保存文件。

标记端口

在浏览器或 VS Code 桌面应用程序中打开 Codespaces 时,你可以标记一个转发端口,以便在列表中更轻松地识别它。

  1. 在 Codespace 中打开终端。

  2. 单击“端口”选项卡。

  3. 右键单击要标记的端口,然后单击设置端口标签

    Screenshot of the pop-up menu for a forwarded port, with the "Set Port Label" option highlighted with an orange outline.

  4. 为你的端口键入一个标签,然后按 Enter。

    Screenshot of the label "Staging" added as a custom label for a forwarded port.

自动标记转发端口

你可以标记一个端口,并将更改写入存储库的开发容器配置文件。如果你对使用 forwardPorts 属性自动转发的端口执行此操作,那么该标签将自动应用于从使用该配置文件的存储库创建的所有未来 Codespaces 的该转发端口。

  1. 在 Codespace 中打开终端。

  2. 单击“端口”选项卡。

  3. 右键单击要将标签属性添加到 Codespaces 配置的端口,然后单击设置标签并更新 devcontainer.json

    Screenshot of the pop-up menu for a forwarded port, with the "Set Label and Update devcontainer.json" option highlighted with an orange outline.

  4. 为你的端口键入一个标签,然后按 Enter。

    Screenshot of the label "Staging" added as a custom label for a forwarded port.

  5. 如果你的存储库有多个开发容器配置文件,系统会提示你选择要更新的文件。

    开发容器配置文件已更新,以便在 portsAttributes 属性中包含新标签。例如

    // Use 'forwardPorts' to make a list of ports inside the container available locally.
    "forwardPorts": [3333, 4444],
    
    "portsAttributes": {
      "3333": {
        "label": "app-standard-preview"
      },
      "4444": {
        "label": "app-pro-preview"
      }
    }
    

在命令行上查看端口标签

当您列出代码空间的已转发端口时,可以看到端口标签。为此,请使用 gh codespace ports 命令,然后选择一个代码空间。

转发端口

有关如何在代码空间中将端口转发到本地计算机上的端口的信息,请参阅 JetBrains 文档中“安全模型”文章的“端口转发”部分。

或者,您可以使用 GitHub CLI 转发端口。有关更多信息,请单击此页面顶部的“GitHub CLI”选项卡。