WSL2 + Webman + Swoole 开发环境搭建实录（上）：环境搭建

WSL2 Webman Swoole 开发环境搭建实录上环境搭建这是一套三篇系列实录记录我从零开始在 WSL2 里搭起 PHP 8.3 Swoole Webman 开发环境的全过程。不是教程是实操记录——包括踩过的坑、绕过的路、以及那些“早知道就好了”的细节。上篇本篇WSL2 基础 → PHP 8.3 → Swoole 6.2.2 → 项目迁移 →composer install跑通中篇Windows MySQL/Redis 远程开放 Git/Gitee VS Code 工作流下篇Webman 配置改造 启动访问 长期稳定运行一、背景与目标1.1 我的机器Windows 本机64GB 内存Intel Xeon E5-2680 v210 核 20 线程477GB SSDWindows 侧已有服务MySQLphpEnv 5.7、RedisphpEnv 6379已有业务数据WSL2 发行版Ubuntu 24.04.1 LTSWSL 内 systemd已开启1.2 为什么要搬到 WSL2说说我真实的想法不是事后编的“标准答案”第一PHP 在 Windows 上支持本来就不好。这不是 Webman 一家的问题是 PHP 生态的普遍情况。很多扩展在 Windows 下要么没有要么版本落后要么行为不一致。既然早晚要上 WSL不如现在就上省得以后业务复杂了再迁移。第二我要上协程。Webman 基于 Workerman在 Windows 上只能跑单进程协程方案Swoole/Swow在 Windows 下要么不可用要么不稳定。我之前在 Windows 上php start.php start跑着跑一段时间内存回收不干净偶发卡死每天要手动重启几次。开发阶段勉强能用但调试体验差——日志、断点、热重载都不如 Linux 顺畅而且和线上 Linux Swoole 环境不一致本地行为不可信。所以决定把 PHP/Swoole/Webman 搬到 WSL2。那为什么 MySQL/Redis 不一起搬因为我 Windows 上本来就有项目在用这两个服务数据也在里面。再在 WSL 里装一套不仅重复还要迁移数据、改连接、维护两套环境。不如直接让 WSL 连 Windows 已有的服务省事。1.3 最终架构┌─────────────────────────────────────────┐ │ Windows 宿主机 │ │ │ │ ┌──────────┐ ┌──────────┐ │ │ │ MySQL │ │ Redis │ │ │ │ :3306 │ │ :6379 │ │ │ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ WSL 通过网关 IP 访问 │ │ │ │ │ │ ┌────┴─────────────┴─────┐ │ │ │ WSL2 Ubuntu │ │ │ │ │ │ │ │ PHP 8.3.6 Swoole 6.2.2 │ │ │ Webman 项目 ~/imSeverBase │ │ │ 监听 0.0.0.0:8181 │ │ └─────────────────────────┘ │ │ │ │ 浏览器访问 http://localhost:8181 │ └─────────────────────────────────────────┘分工原则组件位置原因PHP 8.3 Swoole 6.2.2WSL2 UbuntuWindows 对 PHP 支持差协程方案必须 LinuxMySQL RedisWindows 本机已有服务和数据本地也有项目在用不重复安装Webman 项目代码~/imSeverBaseWSL 家目录不放/mnt/c/避免跨文件系统 IO 性能差IDEVS Code / PhpStormRemote-WSL代码编辑与调试GitWSL 内操作避免 Windows 工具操作 WSL 路径的权限问题1.4 端口规划WSL 内 Webman0.0.0.0:8181Windows MySQL3306Windows Redis6379WSL 不装 MySQL/Redis所以不涉及端口冲突。1.5 明确不做什么不装宝塔WSL 里装宝塔有坑而且我要的是纯命令行环境不在 WSL 里装 MySQL/RedisWindows 已有数据不迁移不把项目放/mnt/c/跨文件系统 IO 性能差权限也乱不做生产部署这是开发环境Windows 常开不休眠二、WSL2 Ubuntu 基础环境2.1 前置条件确认假设你已经装好 WSL2 Ubuntu 24.04并且已经设过用户名密码。如果还没装wsl --install -d Ubuntu-24.04一条命令搞定重启即可。在 WSL 里确认几件事# 确认发行版lsb_release-a# 确认 WSL 版本wsl--version2.2 systemd检测与开启WSL 默认是不开 systemd 的。很多人装完 Ubuntu发现systemctl用不了就是因为这个。后面装 MySQL/Redis 客户端、用systemctl管理服务、跑journalctl看日志都靠它所以先确认它开没开。检测方法方法一直接查 systemd 状态systemctl is-system-running返回可能是running正常在跑degraded在跑但有部分 unit 失败WSL 下常见不影响使用offline或报错System has not been booted with systemd没开方法二查 1 号进程是什么ps-p1-ocomm返回systemd开了返回init或其他没开方法三最直接的systemctl--version能打印出版本号说明 systemd 可用。如果报System has not been booted with systemd as init system (PID 1). Cant operate.就是没开。开启方法编辑/etc/wsl.confsudonano/etc/wsl.conf加[boot] systemdtrue保存后在 Windows PowerShell 里执行wsl--shutdown然后重新打开 WSL 终端再跑一次检测命令应该返回running或degraded。注意事项WSL 版本要求systemd 支持需要 WSL 0.67.6。用wsl --version查版本低了先wsl --update。degraded是正常的WSL 环境不完整某些 unit 启动失败很正常只要不是offline就行。改完必须wsl --shutdown光退出终端不算重启 WSL配置不生效。2.3 忘记 WSL 密码怎么办如果哪天忘了 WSL 用户的登录密码不要慌也不需要重装# 以 root 身份进入 WSLwsl-u root# 修改密码passwd lizhili# 输入新密码两次看到 password updated successfullyexit然后正常wsl进去新密码生效。2.4 .wslconfig 资源限制WSL2 默认会吃掉 Windows 一半内存。我 64GB 机器默认给 WSL 32GB跑 Webman 用不上这么多。在C:\Users\你的用户名\.wslconfig没有就手动创建里加[wsl2] memory8GB processors4 swap4GB我给了 4 核 8G跑 Webman Swoole 足够。保存后 PowerShell 执行wsl --shutdown重开 WSL 验证free-h# Total 应显示约 8Ginproc# 应显示 4注意文件名是.wslconfig不是.wslconfig.txtWindows 默认隐藏扩展名别被坑了[wsl2]段头只写一次如果之前配过networkingModemirrored合并到同一段里改完必须wsl --shutdown才生效补充坑.wslconfig写错会导致 WSL 起不来报 “The specified configuration is not valid”。如果遇到先wsl --shutdown把.wslconfig删掉或改回默认再重启。三、PHP 8.3 Swoole 6.2.2 编译安装3.1 确认 PHP 8.3 就位我用的 Ubuntu 24.04 自带 PHP 8.3.6。先确认php-vphp-m确认关键扩展已就位pcntl、posix、socketsSwoole/Webman 必需pdo_mysql连 MySQLcurl、mbstring、zip常规开发redis如果还没装后面装此时php -m | grep swoole应该是空的Swoole 还没装这是下一步。3.2 安装编译依赖踩坑apt 锁冲突装编译依赖时我遭遇了 Ubuntu 后台自动更新占锁sudoaptinstall-yphp8.3-dev php-pear build-essential autoconf\libssl-dev libcurl4-openssl-dev libc-ares-dev pkg-config报错Waiting for cache lock: Could not get lock /var/lib/dpkg/lock-frontend. It is held by process 14941 (unattended-upgr)原因Ubuntu 的unattended-upgrades服务在后台自动更新占用了 dpkg 锁。处理方式先等几十秒不行就手动解除sudosystemctl stop unattended-upgradessudokill-914941# 换成你实际的 PIDsudorm-f/var/lib/dpkg/lock-frontendsudorm-f/var/lib/dpkg/locksudodpkg--configure-a然后重新执行 apt 安装命令即可。后续可选关闭自动更新避免再次打扰sudosystemctl disable unattended-upgrades补充坑如果dpkg --configure -a报 “dpkg was interrupted”说明之前有中断的安装先跑sudodpkg--configure-asudoapt--fix-brokeninstall再来装依赖。3.3 选择 Swoole 安装方式pecl 而不是 PIE现在 PHP 官方推 PIEPHP Installer for Extensions是新方向。但我第一次装 Swoole 用的是pecl原因pecl 更成熟资料多交互式选项更清晰能逐条选编译参数PIE 现在生态还没完全跟上遇到问题不好搜结论首次装 Swoole 走 peclPIE 作为以后的备选。3.4 pecl install swoole 交互全记录详细版sudopeclinstallswoole这个命令会进入一个交互式问答界面一个接一个问你要不要开某个特性。我第一次装的时候盯着屏幕看了半天每个选项都要判断一下生怕选错。下面把我遇到的每个选项、我选什么、为什么选逐个列出来。选项我的选择原因enable sockets support?yesWebman/Workerman 必需不开这个 Webman 起不来enable openssl support?yes需要 HTTPS/SSL 通信后面连 HTTPS 接口用得上specify openssl installation directory?直接回车不指定Ubuntu 自带 OpenSSL 3.0.13pecl 自动识别不需要手动填路径enable http2 support?yesHTTP/2 支持现代 Web 服务建议开enable mysqlnd support?yes连接 MySQL 必需不开连不上数据库enable curl support?yes协程化 HTTP 客户端Webman 里做 HTTP 请求要走它enable cares support?yes异步 DNS 解析协程环境下 DNS 不阻塞enable brotli support?noBrotli 压缩暂时用不到enable zstd support?noZstd 压缩暂时用不到enable pgsql support?noPostgreSQL我用 MySQLenable odbc support?noODBC用不到enable oracle support?noOracle用不到enable sqlite support?noSQLite用不到enable firebird support?noFirebird用不到enable swoole thread support?noPHP 是 NTS非线程安全版本不能开线程开了会编译失败enable iouring support?noio_uring 是 Linux 新 IO 模型WSL2 内核对 liburing 支持不完整开了可能报错enable async ssh2 support?no异步 SSH2用不到enable async ftp support?no异步 FTP用不到几个关键项解释socketsSwoole 的 socket 通信基础Webman 全靠它必须 yesmysqlndMySQL 原生驱动协程环境下连 MySQL 走它必须 yescurl不是系统 curl是 Swoole 自己的协程 curl不开的话 Webman 里用 Guzzle 之类的会退化成阻塞 IOcares协程 DNS 解析不开的话域名解析会阻塞整个协程threadNTS 版本 PHP 一定选 no不然编译到一半报错白等几分钟iouringWSL2 下建议 no内核版本可能不够开了编译能过但运行时报错更麻烦编译大约2-3 分钟期间会刷很多 gcc 的输出。最后看到Build process completed successfully就说明成功了。补充坑如果编译过程中报fatal error: openssl/ssl.h: No such file or directory说明libssl-dev没装上重新sudo apt install -y libssl-dev。报c-ares相关的错就装libc-ares-dev。报pcre.h not found装libpcre3-dev。补充坑如果 pecl 问了一堆问题之后报错退出可以重新跑sudo pecl install swoole它会重新问一遍。已经编译过的缓存可能还在会快一些。补充坑如果之前已经装过一次 Swoolepecl 会提示 “swoole already installed”要重装得先sudopecl uninstall swoolesudopeclinstallswoole3.5 启用并验证 Swoole创建一个新的 ini 文件echoextensionswoole.so|sudotee/etc/php/8.3/cli/conf.d/20-swoole.ini验证php-m|grepswoole# swoolephp--riswoole|head-20输出应包含swoole enabled Version 6.2.2 coroutine enabled with boost asm context epoll enabled sockets enabled openssl OpenSSL 3.0.13 30 Jan 2024 dtls enabled http2 enabled json enabled验证协程 curlphp--riswoole|grep-icurl# curl-native enabled# curl-version 8.5.0✅ Swoole 6.2.2 安装完成协程/sockets/openssl/curl/mysqlnd/http2/json 全部就绪。四、项目迁移Windows 代码 → WSL4.1 打开 WSL 文件系统在 WSL 终端里cd~ explorer.exe.Windows 资源管理器会弹出/home/lizhili/直接在里面新建imSeverBase文件夹把 Windows 侧现有 Webman 代码复制进去。复制规则✅ 复制app/、config/、public/、composer.json、start.php等业务文件❌ 不复制vendor/Windows 下编译的依赖在 WSL 里不可用❌ 不复制composer.lock避免锁定旧平台版本补充坑如果项目里混着 Windows 换行符CRLF的.sh文件在 WSL 里跑会报bad interpreter。修sudoaptinstalldos2unix dos2unix 你的脚本.sh或者一次性处理find.-name*.sh-execdos2unix{}\;4.2 VS Code 打开项目含路径说明项目的完整路径有两个视角WSL 视角/home/lizhili/imSeverBaseWindows 视角\\wsl.localhost\Ubuntu\home\lizhili\imSeverBaseVS Code 用Remote - WSL打开时走的是 WSL 视角的路径。三种打开方式方式一WSL 终端里用code .推荐cd~/imSeverBase code.code是 VS Code 的 WSL 集成命令.表示当前目录。首次执行会自动在 WSL 里装 VS Code Server左下角出现WSL: Ubuntu即成功。方式二VS Code 里手动打开VS Code 左下角点绿色图标或CtrlShiftP→Remote-WSL: New Window连接后File→Open Folder地址栏输入/home/lizhili/imSeverBase回车方式三Windows 资源管理器里右键在\\wsl.localhost\Ubuntu\home\lizhili\imSeverBase目录下右键 →Open with Code。但这种方式有时不灵不如前两种稳。如果code .提示command not found说明 VS Code 的 WSL 集成没装好。在 Windows 的 VS Code 里执行一次CtrlShiftP→Remote-WSL: New Window它会自动在 WSL 里配好code命令。然后回 WSL 终端重试code .。补充坑如果你的项目不在~/imSeverBase而是在别的路径cd到实际项目目录再code .。路径里不要带空格带了的话用引号包起来cd /home/lizhili/my project。4.3 PhpStorm 打开项目WSL 配置PhpStorm 和 VS Code 的 WSL 集成方式完全不同。VS Code 是“在 WSL 里跑一个 Server”PhpStorm 是“Windows 端 IDE 通过远程解释器连到 WSL 里的 PHP”。所以 PhpStorm 需要手动配一次远程解释器配好之后体验就很顺。前提条件PhpStorm 2023.1 或更高版本WSL 支持需要 Professional 版Windows 10 build 18917WSL 2 要求WSL 发行版已装好PHP 8.3 已就位配置步骤第一步打开设置CtrlAltS→Languages Frameworks→PHP第二步配置 CLI Interpreter在CLI Interpreter下拉框旁边点...按钮打开CLI Interpreters对话框。点左上角→ 选择From Docker, Vagrant, VM, WSL, Remote...。第三步选择 WSL 方式在弹出的Configure Remote PHP Interpreter对话框中字段填写内容Linux distribution下拉选Ubuntu-24.04你实际装的发行版PHP interpreter path填/usr/bin/phpPhpStorm 默认建议/usr/local/bin/php但 Ubuntu apt 装的 PHP 在/usr/bin/php以which php输出为准点OKPhpStorm 会自动检测 WSL 里的 PHP 版本和已加载的扩展确认无误后保存。第四步验证配置好后PhpStorm 底部状态栏会显示 PHP 版本和解释器名称。打开一个.php文件代码补全、跳转、语法检查都会基于 WSL 里的 PHP 环境而不是 Windows 上的。PhpStorm vs VS CodeWSL 下怎么选维度VS CodePhpStormWSL 集成方式在 WSL 里跑 Server开箱即用Windows 端 IDE 连 WSL 远程解释器需手动配配置复杂度低code .就行中需要配远程解释器PHP 代码智能靠插件中等原生深度支持重构/索引更强Xdebug 调试需额外配置原生集成配置更顺资源占用轻量较重但 WSL 下解释器在 Linux 侧Windows 侧负担可控多语言支持强插件生态丰富PHP 为主其他语言支持一般我的建议两个都留着混合用。VS Code 用于快速打开、改配置、跑终端PhpStorm 用于写业务代码、重构、调试。两个 IDE 打开的是同一个 WSL 路径/home/lizhili/imSeverBase互不干扰Git 操作统一走 WSL 终端。补充坑PhpStorm 的 Terminal 默认可能是 Windows 的cmd.exe需要手动改成 WSL 终端。Settings→Tools→Terminal→Shell path填wsl.exe -d Ubuntu-24.04补充坑如果 PhpStorm 里代码跳转正常但运行报错说找不到php命令检查Settings→PHP→CLI Interpreter里选的是不是 WSL 解释器而不是 Local 的 Windows PHP。五、composer install 踩坑与解决5.1 报错缺 ext-gdphpoffice/phpspreadsheet 2.4.6 requires ext-gd topthink/think-image v1.0.8 requires ext-gd webman/captcha v1.0.5 requires ext-gd解决sudoaptinstall-yphp8.3-gd php-m|grepgd5.2 报错ext-redis 版本冲突symfony/cache v7.4.14 conflicts with ext-redis 6.1原因apt 源里的php-redis版本是 5.3.7太低。symfony/cache 要求 6.1。解决通过 pecl 装 redis 6.3.0sudopeclinstallredis这个也是交互式的会问一堆 yes/no选项我的选择原因enable igbinary serializer support?yesigbinary 是更高效的序列化Redis 存复杂结构时体积更小、速度更快系统已装 igbinary 扩展enable lzf compression support?noLZF 压缩用不到enable zstd compression support?noZstd 压缩用不到enable msgpack serializer support?noMsgpack 序列化暂时不用enable lz4 compression support?noLZ4 压缩用不到use system liblz4?不出现前面 lz4 选了 no如果 lz4 选 yes 才会问这个enable json serializer support?noJSON 序列化用不到enable brotli compression support?noBrotli 压缩用不到关键项解释igbinary如果系统里有 igbinary 扩展php -m | grep igbinary选 yes 能显著提升 Redis 读写性能序列化后的数据更小其他压缩/序列化本地开发用不到全 no减少依赖编译完后启用sudotee/etc/php/8.3/cli/conf.d/20-redis.iniEOF extensionredis.so EOF验证php--riredis|head-3# redis enabled# Version 6.3.0补充坑如果之前用 apt 装过php8.3-redispecl 装的 redis 会和 apt 的冲突出现 “Module ‘redis’ already loaded”。处理sudoaptremove php8.3-redissudophpenmod-v8.3redis# 如果还有别的 ini 文件残留ls/etc/php/8.3/cli/conf.d/|grepredis保留20-redis.ini一个就行。补充坑pecl 装 redis 时如果提示 “igbinary not found” 但你还是选了 yes编译会失败。先确认php -m | grep igbinary有输出没有就先装 igbinarysudo pecl install igbinary再装 redis。5.3 再次 composer installcd~/imSeverBasecomposerinstall依赖安装成功无平台冲突。补充坑如果 composer install 卡在 “Loading composer repositories” 很久说明在拉 Packagist 官方源。换成国内镜像composerconfig-grepo.packagistcomposerhttps://mirrors.aliyun.com/composer/这个换源操作下篇还会提但第一次装依赖时就换掉体验更顺。六、本篇小结到这一步WSL 里已经具备组件状态WSL2 Ubuntu 24.04.1 LTS✅ systemd 开启PHP 8.3.6✅ 扩展齐全Swoole 6.2.2✅ 协程 / curl / openssl / sockets 全开ext-gd✅ 已安装ext-redis 6.3.0✅ 已安装Webman 项目~/imSeverBase✅ 代码就位composer install✅ 依赖装完无平台冲突VS Code Remote-WSL✅ 可正常编辑PhpStorm WSL 解释器✅ 已配置需手动配远程解释器但是还不能跑起来Webman 要连的 MySQL 和 Redis 还在 Windows 上WSL 现在还连不上它们。下一篇会处理Windows MySQL / Redis 开放远程访问bind、授权、防火墙WSL 里装 MySQL/Redis 客户端并测试连通Git / Gitee / VS Code 工作流Webman 配置改造硬编码 →getenv().env这是 2026-09 的版本后面还会继续踩坑有更新会补进来。