Composer在高性能网关（Hyperf Nano）项目中的环境适配（配置演示）-composer-PHP中文网

hyperf nano 项目必须用 composer 精确控制 php 版本、扩展启用状态和 autoloader 行为，否则启动即报 class 'swoolehttpserver' 或 undefined function coroutine_create()；需在 composer.json 中硬约束 php ≥8.1 及必需扩展，精简 psr-4 映射为 "app" → "app/" 和 "hyperf ano" → "vendor/hyperf/nano/src/"，并执行 composer dump-autoload -o，同时全局配置阿里云镜像且禁用 --no-scripts 以确保环境稳定。

composer在高性能网关（hyperf nano）项目中的环境适配（配置演示）

Hyperf Nano 项目必须用 Composer 精确控制 PHP 版本、扩展启用状态和 autoloader 行为，否则启动即报 Class 'SwooleHttpServer' 或 undefined function coroutine_create() —— 这不是代码问题，是 Composer 没把环境“校准”到位。

PHP 版本与扩展必须在 composer.json 中硬约束

Hyperf Nano 基于 Swoole 协程运行，不支持 PHP 7.4 以下版本，且 swoole、json、mbstring、openssl、curl 必须全部启用（非仅安装）。仅靠 php -v 和 php -m 检查不够，Composer 会在 install / update 阶段根据 composer.json 的 platform 配置做兼容性预判。

在 composer.json 根节点添加：

"config": {
  "platform": {
    "php": "8.1.0"
  }
}

同时在 require 中显式声明扩展依赖（触发 Composer 安装前校验）：

"require": {
  "php": ">=8.1.0",
  "ext-swoole": "*",
  "ext-json": "*",
  "ext-mbstring": "*",
  "ext-openssl": "*",
  "ext-curl": "*"
}

若本地 PHP 不满足，composer install 会直接失败并提示缺失扩展，而不是装完再崩 —— 这比 runtime 报错早得多，也更容易定位

autoload 配置必须匹配 Nano 的精简目录结构

Hyperf Nano 默认没有 src/ 下的多层嵌套命名空间，它的 app/ 目录直出控制器、服务、中间件等类，但默认 composer.json 的 PSR-4 映射仍沿用完整 Hyperf 的路径（如 "HyperfHttpServer": "src/http-server/src/"），这会导致 AppControllerIndexController 找不到文件。

Hyperframes Creative

HyperFrames视频非动画创意指导，包括设计规范（frame.md/design.md）处理、配色、字体设计、旁白及节奏规划等。

下载

删掉所有无关的 psr-4 映射，只保留 Nano 实际使用的两处：

"autoload": {
  "psr-4": {
    "App\": "app/",
    "Hyperf\Nano\": "vendor/hyperf/nano/src/"
  }
}

务必运行 composer dump-autoload -o（加 -o 启用优化加载器），否则协程环境下类加载延迟明显，首次请求可能超时
不要在 autoload-dev 里塞测试类路径 —— Nano 项目通常不跑 PHPUnit，这类路径会污染生产 autoload map，增加内存占用

镜像、锁文件与 no-scripts 组合使用才稳定

Hyperf Nano 体积小，但对依赖版本极其敏感：一个 hyperf/utils 的 patch 版本差异就可能导致 ApplicationContext::getContainer() 返回 null。国内网络下直接连 packagist.org 极易因超时导致 composer.lock 写入不全，后续部署必然出错。

全局切镜像（一次设置，永久生效）：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
创建项目时禁用自动脚本，防止权限或路径问题中断初始化：composer create-project hyperf/nano-skeleton my-gateway --no-scripts
进项目后手动执行关键初始化：php bin/hyperf.php vendor:publish（发布配置）、php bin/hyperf.php gen:controller Api/Index（生成示例）
确认 composer.lock 文件存在且非空，再提交到 Git —— 没有 lock 文件的 Nano 项目等于没锁定环境

最容易被忽略的是 platform 配置和 dump-autoload -o 的组合：前者让 Composer 在安装阶段就拦住不兼容环境，后者让类加载走静态映射而非实时扫描。这两步不做，你在 Docker 里反复 rebuild 镜像，其实只是在重复同一个环境错配问题。