Devcontainers 技术文档

镜像概述和主要用途

Devcontainers 是针对 PHP 和 Node.js 开发优化的容器化开发环境，也可作为 Codespace 使用。该环境旨在提供一致、隔离且高效的开发体验，支持多种主流 PHP 和 Node.js 项目框架，简化开发环境配置流程，适用于个人开发及团队协作场景。

核心功能和特性

• 多框架兼容：支持 Laravel、Symfony、NestJS、SailsJS、WordPress、Drupal、Magento、Prestashop、Opencart 等 PHP 和 Node.js 项目，理论上兼容所有基于 PHP/Node.js 的开发项目。
• 优化的资源配置：默认 CPU/内存限制适配中大型项目（如 Laravel、Magento），可根据需求调整，避免多服务（数据库、Elasticsearch 等）并发运行时的资源冲突。
• 隔离的开发环境：通过 Docker 容器隔离项目依赖，避免本地环境污染；用户目录通过 Docker 卷挂载，持久化开发配置。
• 多项目工作区支持：支持在 /projects 目录下创建多项目文件夹，实现前端与 API 等关联项目的统一管理。
• 无缝工具集成：自动同步本地 Git 配置（用户名、邮箱、GPG 等）和 SSH 密钥，支持 VSCode 远程容器扩展，简化开发工具链配置。

使用场景和适用范围

• PHP/Node.js 项目开发：适用于基于 Laravel、Symfony、NestJS 等框架的日常开发、调试和测试。
• 多项目协同开发：需同时维护前端（如 Vue/React）和后端（如 PHP API）的场景，可在同一工作区管理多个项目。
• 团队环境标准化：通过统一的容器配置，确保团队成员使用一致的开发环境，减少“在我电脑上能运行”问题。
• 轻量设备远程开发：支持连接远程 Docker 服务，可在本地轻量设备（如笔记本）上通过 VSCode 连接远程高性能服务器进行开发。

快速开始

环境准备

1. 安装依赖工具

   • 安装 Docker 并确保其正常运行（支持本地或远程 Docker 服务）。
   • 安装 Visual Studio Code。
   • 安装 VSCode 扩展：Remote - Containers。
   • （可选）安装 Git 并完成基础配置（用户名、邮箱等）：

     git config --global user.name "Your Name"
     git config --global user.email "***"
     

2. 获取项目模板

   • 下载 项目模板 ZIP 包（仅克隆仓库用于贡献）。
   • 解压后重命名目录（将作为 Docker 命名空间，建议与项目名称一致）。

配置修改

1. 设置项目名称
   编辑 .devcontainer/devcontainer.json，修改项目名称（确保不同项目名称唯一，实现存储隔离）。

2. 调整服务与资源
   编辑 docker-compose.yml：

   • 取消注释或添加所需服务（如数据库、Elasticsearch 等）。
   • 根据需求调整 CPU 和内存限制（默认配置适用于中大型项目，16GB 内存环境下支持多服务并发）。

启动开发环境

1. 打开项目：在 VSCode 中打开重命名后的项目目录。
2. 启动远程容器：
   • VSCode 会提示“在容器中打开”，点击确认；或通过左下角状态栏的远程容器图标（><）选择“Reopen in Container”。
   • 首次启动时，Docker 将自动构建镜像并启动容器，过程可能需要几分钟。

详细配置说明

核心配置文件

devcontainer.json

用于定义 VSCode 远程容器配置，关键参数：

• name：项目名称（需唯一，影响容器命名和存储隔离）。
• dockerComposeFile：指定 docker-compose.yml 路径（默认指向项目根目录）。
• service：指定主服务容器（默认通常为 workspace）。
• extensions：预安装的 VSCode 扩展列表（可在此添加项目所需扩展，如 PHP 调试器、ESLint 等）。

docker-compose.yml

定义开发环境中的服务组合，主要服务及配置说明：

端口映射规则：左侧为宿主机端口（可修改以避免冲突），右侧为容器内端口（不建议修改，除非明确容器内服务配置）。

SSH 集成

1. 生成 SSH 密钥（首次使用）：
   按 GitHub 文档 生成 SSH 密钥。
2. 自动同步密钥：VSCode 远程容器扩展会自动检测并同步本地 SSH 密钥，无需在容器内重复配置。

Git 配置同步

本地 Git 全局配置（用户名、邮箱、GPG 等）会自动同步至容器环境，确保提交信息与本地一致。

使用示例

创建 Laravel 项目

1. 在 VSCode 终端中执行以下命令创建项目：

   composer create-project laravel/laravel .
   

2. 配置数据库连接：编辑 .env 文件，设置数据库主机为 mariadb（对应 docker-compose.yml 中的服务名）：

   DB_HOST=mariadb
   DB_USERNAME=developer
   DB_PASSWORD=developer
   

3. 启动开发服务器：

   php artisan serve --host=0.0.0.0
   

   服务将通过宿主机 8000 端口暴露，可在浏览器访问 [***]。

多项目工作区配置

1. 在 /projects 目录下创建子文件夹（如 api、frontend）。
2. 在 VSCode 中通过“文件 > 添加文件夹到工作区”将子文件夹添加至当前工作区，实现多项目统一管理（如前端与后端分离项目）。

Prettier 配置（PHP 格式化）

1. 安装依赖：

   npm install --save-dev prettier @prettier/plugin-php
   

2. 在项目根目录创建 .prettierrc 文件，配置格式化规则（示例）：

   {
     "printWidth": 120,
     "tabWidth": 4,
     "singleQuote": true
   }
   

高级设置

修改配置后的更新

• 修改 devcontainer.json（如添加扩展、调整工作区设置）：无需重建容器，VSCode 会自动应用，建议同步更新配置文件至版本库。
• 修改 docker-compose.yml（如增减服务、调整资源限制）：需通过 VSCode 远程容器扩展触发重建（点击左下角图标，选择“Rebuild Container”）。

用户卷管理

开发用户目录（如 /home/developer）通过 Docker 卷挂载，以持久化用户配置（如 VSCode 设置、工具偏好）。若需重置用户环境：

1. 关闭 VSCode 远程连接。
2. 删除主容器及用户卷：

   docker rm -f <container-name>  # 替换为实际容器名
   docker volume rm <user-volume-name>  # 卷名通常包含项目名称和“user”前缀
   

注意事项

• 端口冲突：确保本地未占用 8000、8080、3000、3306 等默认端口（或在 docker-compose.yml 中修改宿主机端口，如 8001:8000）。
• 服务资源：禁用非必需服务（如 Elasticsearch）以减少资源消耗，尤其在内存有限的环境中。
• 远程 Docker 配置：Windows/macOS 用户如需连接远程 Docker 服务，建议通过 Chocolatey（Windows）或 Brew（macOS）安装 docker-cli。