koel 官方不支持 windows 环境，phpenv 虽可尝试部署但存在路径解析、ffmpeg 兼容、koel:scan 静默退出等核心问题；实测需修改 scancommand.php 为 file::allfiles()、用 powershell 构建前端、强制 migrate:fresh --seed 并清理缓存，且后续维护极不稳定。
phpEnv 本身不是官方支持 Koel 的运行环境，它是一个 Windows 下的 PHP 集成环境（类似 XAMPP、WAMP），但 Koel 官方明确不推荐、也不测试 Windows 环境部署，**绝大多数失败都卡在路径处理、文件监听、FFmpeg 兼容性或 php artisan koel:scan 命令静默退出这几个环节**。
如果你已在 Windows 上装了 phpEnv，又坚持想试，下面这些是实测中真正起作用的步骤和必须绕开的坑。
确认 phpEnv 环境是否满足最低要求
打开 phpEnv 控制面板，检查以下三项是否启用且版本匹配：
- PHP 版本 ≥ 8.1（
php -v输出必须含8.1.或更高；7.x 会报Attribute "readonly" does not exist类错误） - 已开启
openssl、pdo_mysql、mbstring、fileinfo、exif扩展（缺任意一个，composer install会中断或koel:init报数据库连接失败） - MySQL 服务已启动，且能用命令行登录（例如
mysql -u root -p）——仅靠 phpMyAdmin 能连 ≠ CLI 能连
克隆代码后必须改两处硬编码路径
Koel 的 php artisan koel:scan 在 Windows 下默认用 glob() 扫描，而 phpEnv 的 Apache + PHP-CGI 模式下，glob("D:/music/*.mp3") 会返回空数组，不是权限问题，是 PHP 内部路径解析 bug。
解决办法：手动编辑 app/Console/Commands/ScanCommand.php，找到类似这行：
foreach (glob($path . '/*.{mp3,flac,ogg,wav,m4a}', GLOB_BRACE) as $file) {
替换成：
$files = \Illuminate\Support\Facades\File::allFiles($path);
foreach ($files as $file) {
if (in_array($file->getExtension(), ['mp3', 'flac', 'ogg', 'wav', 'm4a'])) {
否则扫描永远显示 “0 songs imported”，日志里也看不到错误。
npm 构建必须用 PowerShell（不是 cmd，也不是 Git Bash）
phpEnv 自带的 Node.js 通常没配好 npm 权限，npm install 或 npm run build 在 cmd 里大概率卡在 node-gyp rebuild 或报 EPERM: operation not permitted。
正确做法：
- 用 Windows PowerShell（以管理员身份运行）
- 进入项目目录后，先执行：
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser - 再运行：
npm install --no-optional（跳过fsevents等 macOS 专用包） - 构建前端时用：
npm run prod（别用dev，Windows 下 Vite HMR 经常失灵）
数据库初始化后务必清空缓存并重跑迁移
即使 php artisan koel:init 显示成功，首次访问页面仍可能报 SQLSTATE[42S02]: Base table or view not found —— 这是因为 Laravel 缓存了旧的 migration 状态，而 phpEnv 的 MySQL 默认没开 innodb_file_per_table，导致某些表创建失败但不报错。
补救操作（按顺序）：
- 删掉
bootstrap/cache/config.php和bootstrap/cache/packages.php - 执行：
php artisan config:clear && php artisan cache:clear - 再执行：
php artisan migrate:fresh --seed（强制重装所有表+初始数据） - 最后：
php artisan storage:link（否则封面图 404）
phpEnv 下能跑起来，但音乐库同步、后台任务、WebP 封面生成等特性不稳定，**真正的痛点不在安装，而在后续维护——每次 Windows 更新、杀毒软件升级或 phpEnv 升级，都可能让 koel:scan --watch 彻底失效，且无日志可查**。如果只是想听本地音乐，用 http-server + MusicBrainz Picard 手动整理元数据，反而更省心。php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
