安装说明

本文档详细介绍 Viswoole 框架的环境要求、安装步骤以及依赖管理方式。

环境要求

依赖项	最低版本	说明
PHP	>= 8.3	需要 PHP 8.3 或更高版本
Swoole 扩展	>= 5.1	Swoole 协程引擎，框架核心依赖
sockets 扩展	*	PHP 内置扩展，通常已默认安装
Composer	最新版	PHP 包管理器，用于安装项目依赖

注意：Viswoole 基于 Swoole 协程运行，不支持传统的 PHP-FPM / Nginx/Apache 部署模式。服务通过内置的 CLI 命令直接启动。

安装 Swoole 扩展

Swoole 是 Viswoole 的核心运行时依赖。请根据你的系统选择合适的安装方式：

通过 pecl 安装（推荐）

bash

pecl install swoole

安装完成后，在 php.ini 中添加扩展配置：

ini

extension=swoole.so

通过源码编译安装

bash

# 克隆 Swoole 源码
git clone https://github.com/swoole/swoole.git
cd swoole

# 编译安装（需要 phpize 和 php-config）
phpize
./configure
make && make install

同样需要在 php.ini 中启用扩展。

验证安装

在终端中执行以下命令验证 Swoole 是否正确安装：

bash

php --ri swoole

如果看到 Swoole 的版本信息和配置详情，说明安装成功。

text

swoole

Swoole => enabled
Author => Swoole Team <team@swoole.com>
Version => 5.1.0
...

创建项目

确保环境就绪后，使用 Composer 创建 Viswoole 项目：

bash

composer create-project viswoole/viswoole myProject

执行过程会自动完成以下操作：

下载 viswoole/framework 核心包及所有依赖
生成标准的项目目录结构
创建默认的配置文件和示例代码

安装依赖

进入项目目录后，安装 Composer 依赖：

bash

cd myProject
composer install

自动初始化脚本

composer install 完成后，Composer 会自动触发 post-autoload-dump 钩子，依次执行以下初始化命令：

bash

php viswoole vendor:publish    # 发布框架资源文件到项目目录
php viswoole service:discover   # 扫描并注册服务提供者
php viswoole command:discover   # 扫描并注册自定义命令

这些命令会在首次安装和每次 composer dump-autoload 后自动运行，确保框架资源和服务保持同步。

环境配置

项目根目录包含 .example.env 环境变量模板文件。将其复制为 .env 并根据实际情况修改：

bash

cp .example.env .env

.env 文件中的主要配置项：

yaml

# 应用调试模式（生产环境建议设为 false）
APP_DEBUG=true

# 默认时区
DEFAULT_TIMEZONE=Asia/Shanghai

# 默认启动的服务名称
DEFAULT_START_SERVER=http

# Redis 配置（如需使用缓存功能）
REDIS_HOST=127.0.0.1

# 数据库配置（如需使用 ORM 功能）
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_NAME=test
DATABASE_USER=root
DATABASE_PASSWORD=your_password

安全提示：.env 文件包含敏感信息，请务必将其加入 .gitignore，避免提交到版本控制系统。

IDE 支持

为了获得更好的开发体验（代码补全、类型提示等），建议安装 Swoole IDE Helper：

bash

composer require --dev swoole/ide-helper

该包仅用于开发环境，提供 Swoole 扩展的类型定义文件，不会影响生产环境。

更新框架

如需单独更新 Viswoole 框架核心包：

bash

composer update viswoole/framework

更新完成后建议重新执行初始化命令以确保资源同步：

bash

composer dump-autoload

常见问题

Q: 提示 `ext-swoole` 未找到？

A: 请确认 Swoole 扩展已在当前使用的 PHP 版本中正确安装。可通过 php -m \| grep swoole 检查。

Q: Composer 创建项目失败？

A: 可能是网络问题导致无法从 Packagist 下载包。可尝试：

配置国内镜像源：composer config repo.packagist composer https://mirrors.aliyun.com/composer/
使用代理：composer config -g http_proxy http://your-proxy:port

Q: sockets 扩展未安装？

A: 在大多数 Linux 发行版中可通过包管理器安装：

Ubuntu/Debian: sudo apt-get install php8.3-sockets
CentOS/RHEL: sudo yum install php83-php-sockets
macOS (Homebrew): 通常随 PHP 已包含