为 GitHub Codespaces 设置 PHP 项目

简介

本指南向您展示如何使用 Visual Studio Code Web 客户端在 GitHub Codespaces 中设置示例 PHP 项目。它将引导您完成在 codespace 中打开项目以及添加和修改预定义开发容器配置的过程。

完成本教程后，你将能够使用 VS Code Web 客户端或 VS Code 桌面应用程序，将 dev 容器配置添加到自己的仓库中。

有关 dev 容器的更多信息，请参阅 dev 容器简介。

步骤 1：在代码空间中打开项目

1. 如果尚未登录，请登录 GitHub.com。

2. 前往 https://github.com/microsoft/vscode-remote-try-php。

3. 点击 Use this template（使用此模板），然后点击 Open in a codespace（在代码空间中打开）。

   

当您创建 codespace 时，您的项目会在专属于您的远程虚拟机上创建。默认情况下，codespace 的容器已预装多种语言和运行时，包括 PHP。它还包含常用工具集合，如 Composer、XDebug、Apache、pecl、nvm、git、lynx 和 curl。

你可以通过调整 vCPU 与 RAM 的配额、添加 dotfiles 来个性化环境，或修改已安装的工具和脚本来自定义代码空间。更多信息请参见 自定义你的代码空间。

GitHub Codespaces 使用名为 devcontainer.json 的文件来配置在代码空间中工作的开发容器。每个仓库可以包含一个或多个 devcontainer.json 文件，以提供恰好满足代码在代码空间中工作所需的开发环境。

启动时，GitHub Codespaces 会读取 devcontainer.json 文件及其所有依赖文件，安装所需的工具和运行时，并执行项目所需的其他设置任务。更多信息请参见 dev 容器简介。

步骤 2：添加 dev 容器配置

GitHub Codespaces 的默认开发容器（即 “dev container”）能够让您顺利在类似 vscode-remote-try-php 的 PHP 项目上工作。不过，我们建议您自行配置 dev container，包含项目所需的所有工具和脚本，从而为仓库中的所有 GitHub Codespaces 使用者提供完全可复现的环境。

要让仓库使用自定义 dev 容器，需要创建一个或多个 devcontainer.json 文件。你可以在 Visual Studio Code 中从预定义的配置模板添加，也可以自行编写。有关 dev 容器配置的更多信息，请参见 dev 容器简介。

1. 打开 Visual Studio Code 命令面板（Shift+Command+P / Ctrl+Shift+P），开始输入 “add dev”。点击 Codespaces: Add Dev Container Configuration Files。

   

2. 点击 创建新配置。

3. 在本示例中，你创建代码空间时所使用的模板仓库已经包含了 dev 容器配置，因此会显示一条信息提示配置文件已存在。我们将覆盖现有配置文件，请点击 继续。

4. 点击 显示所有定义。

   

5. 输入 php 并点击 PHP。如果您的项目使用特定工具，还可以选择其他选项。例如，PHP & MariaDB。

6. 选择您想在项目中使用的 PHP 版本。本例中，选中标记为“（默认）”的版本。

7. 会显示一系列可安装的附加功能。我们将安装 GitHub CLI——一款用于在命令行与 GitHub 交互的工具。要安装此工具，输入 github，选择 GitHub CLI，然后点击 OK，再选择 Keep defaults。

8. 系统提示 dev 容器配置文件已存在。点击 覆盖。

   已创建 devcontainer.json 文件，并在编辑器中打开。

自定义 dev 容器配置的详细信息

在 Visual Studio Code 资源管理器中，你会看到项目根目录下新增了一个 .devcontainer 目录，里面包含 devcontainer.json 文件。这是从该仓库创建的代码空间的主要配置文件。

devcontainer.json

你刚添加的 devcontainer.json 将包含 name、image 与 features 等属性的值。文件中还包含了一些可能有用但已被注释掉的额外属性。

文件内容大致如下，具体取决于你选择的镜像。

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/php
{
  "name": "PHP",
  // Or use a Dockerfile or Docker Compose file. More info: https://containers.net.cn/guide/dockerfile
  "image": "mcr.microsoft.com/devcontainers/php:1-8.2-bullseye",

  // Features to add to the dev container. More info: https://containers.net.cn/features.
  // "features": {},

  // Configure tool-specific properties.
  // "customizations": {},

  // Use 'forwardPorts' to make a list of ports inside the container available locally.
  "forwardPorts": [
    8080
  ],
  "features": {
    "ghcr.io/devcontainers/features/github-cli:1": {}
  }

  // Use 'postCreateCommand' to run commands after the container is created.
  // "postCreateCommand": "sudo chmod a+x \"$(pwd)\" && sudo rm -rf /var/www/html && sudo ln -s \"$(pwd)\" /var/www/html"

  // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
  // "remoteUser": "root"
}

• name: 你可以随意为 dev 容器命名，系统会提供一个默认值。
• image: 用于创建代码空间 dev 容器的容器镜像名称，来源于容器注册表（DockerHub、GitHub Container Registry 或 Azure Container Registry）。
• features: 一个或多个对象的列表，每个对象引用可用的 dev 容器功能之一。Features 是自包含、可共享的安装代码和容器配置单元，能够为你的开发容器轻松添加更多工具、运行时或库。你可以在 VS Code 中或在 GitHub 上的 devcontainer.json 编辑器中添加功能。更多信息请查看 Visual Studio Code 或 Web browser 选项卡 中的 “在 devcontainer.json 文件中添加功能”。
• forwardPorts: 此处列出的所有端口都会自动转发。更多信息请参见 代码空间端口转发。
• postCreateCommand: 使用此属性在代码空间创建后运行命令。它可以是字符串（如上所示）、数组或对象。更多信息请参阅 Development Containers 网站上的 dev containers 规范。
• customizations: 此属性允许在代码空间中使用特定工具或服务时进行自定义，例如为 VS Code 配置特定设置和扩展。更多信息请参阅 Development Containers 网站上的 Supporting tools and services。
• remoteUser: 默认情况下您以 vscode 用户身份运行，也可以选择将其设为 root。有关可用属性的完整列表，请参阅 开发容器规范（Development Containers 网站）。

其它 dev 容器配置文件

如果你熟悉 Docker，除了 devcontainer.json，还可以使用 Dockerfile 或 Docker Compose 来配置代码空间环境，只需将 Dockerfile 或 compose.yaml 与 devcontainer.json 放在同一目录下即可。更多信息请参考 Development Containers 网站上的 使用镜像、Dockerfile 与 Docker Compose。

步骤 3：修改你的 devcontainer.json 文件

在添加了 dev 容器配置并基本了解各属性作用后，你现在可以进一步自定义环境。本示例将添加以下属性：

• 在 dev container 创建完成后，运行 composer install，以安装 composer.json 文件中列出的依赖。
• 在此 codespace 中自动安装 VS Code 扩展。

1. 在 devcontainer.json 文件中，删除关于 features 的两行已注释代码。

   // Features to add to the dev container. More info: https://containers.net.cn/features.
   // "features": {},
   

2. 按如下方式编辑 customizations 属性，以安装 “Composer” 扩展。

   JSONC

   // Configure tool-specific properties.
   "customizations": {
     // Configure properties specific to VS Code.
     "vscode": {
       "extensions": [
         "ikappas.composer"
       ]
     }
   },
   

3. 在 features 属性后添加一个逗号。

   "features": {
     "ghcr.io/devcontainers/features/github-cli:1": {}
   },
   

4. 取消注释 postCreateCommand 属性，并在末尾添加文本，以在存在 composer.json 文件时运行 composer install 命令。（现有的命令仅是一些设置步骤，使 Apache 能访问工作区中的文件。）

   JSONC

   // Use 'postCreateCommand' to run commands after the container is created.
   "postCreateCommand": "sudo chmod a+x \"$(pwd)\" && sudo rm -rf /var/www/html && sudo ln -s \"$(pwd)\" /var/www/html; if [ -f composer.json ];then composer install;fi"
   

此时 devcontainer.json 文件应类似如下，具体取决于你选择的镜像。

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/php
{
  "name": "PHP",
  // Or use a Dockerfile or Docker Compose file. More info: https://containers.net.cn/guide/dockerfile
  "image": "mcr.microsoft.com/devcontainers/php:1-8.2-bullseye",

  // Configure tool-specific properties.
  "customizations": {
    // Configure properties specific to VS Code.
    "vscode": {
      "extensions": [
        "ikappas.composer"
      ]
    }
  },

  // Use 'forwardPorts' to make a list of ports inside the container available locally.
  "forwardPorts": [
    8080
  ],
  "features": {
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },

  // Use 'postCreateCommand' to run commands after the container is created.
  "postCreateCommand": "sudo chmod a+x \"$(pwd)\" && sudo rm -rf /var/www/html && sudo ln -s \"$(pwd)\" /var/www/html; if [ -f composer.json ];then composer install;fi"

  // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
  // "remoteUser": "root"
}

1. 保存更改。

2. 打开 VS Code 命令面板（Shift+Command+P / Ctrl+Shift+P），输入 “rebuild”。点击 Codespaces: Rebuild Container。

   

   提示

   有时你可能需要执行完整的重建，以清除缓存并使用全新镜像重新构建容器。更多信息请参见 代码空间中的容器重建。在代码空间内部进行重建可以确保更改在提交到仓库前如预期般工作。如果出现故障，系统会将你置于带有恢复容器的代码空间，你可以从中重新构建以继续调整容器。

   在 dev container 重新构建并且 codespace 再次可用后，postCreateCommand 将已执行，Composer 依赖会被安装，同时 “Composer” 扩展也可供使用。

步骤 4：运行你的应用程序

在上一节中，您已修改 postCreateCommand 以通过 composer install 安装一组包。依赖现在已安装，您可以运行应用程序。不过，在此场景下我们首先需要更改 Apache 监听的端口。我们正在转发 8080 端口，因此要指示 Apache 使用该端口，而不是默认的 80 端口。

1. 在 codespace 的终端中，输入

   Shell

   sudo sed -i 's/Listen 80$//' /etc/apache2/ports.conf
   

2. 然后，输入

   Shell

   sudo sed -i 's/<VirtualHost \*:80>/ServerName 127.0.0.1\n<VirtualHost \*:8080>/' /etc/apache2/sites-enabled/000-default.conf
   

3. 随后使用其控制工具启动 Apache

   Shell

   apache2ctl start
   

4. 当项目启动后，VS Code 右下角会显示一条 “toast” 通知，告知你的应用已在转发的端口上可用。要查看运行中的应用，请点击 在浏览器中打开。

步骤 5：提交你的更改

对代码空间进行更改后（无论是新代码还是配置），你都应提交这些更改。将配置提交到仓库可以确保以后任何人在此仓库创建代码空间时都能获得相同的配置。你所做的任何自定义（例如添加 VS Code 扩展）都将对所有用户生效。

本教程中，你是从模板仓库创建的代码空间，因此代码尚未存储在仓库中。你可以通过将当前分支发布到 GitHub 来创建仓库。

相关信息请参阅 在代码空间中使用源代码管理。

后续步骤

现在，您应该能够为自己的 PHP 项目添加自定义 dev container 配置。

以下是一些面向更高级场景的补充资源。

• 向 devcontainer.json 文件添加功能
• 管理您针对 GitHub Codespaces 的帐户特定密钥
• 管理 GitHub Codespaces 的 GPG 验证
• 在代码空间中转发端口