#在 WSL 上安装 PHP 8.5 和 music-dl 的踩坑记录

想在 Windows 上玩 music-dl，一个 PHP 写的命令行音乐搜索下载工具，结果踩了一堆坑，记录一下。最终用ondrej PPA解决了安装问题。

#我本身对PHP不熟悉，用Claude查找依赖，扩展列表已经清楚了。大部分是 PHP 内置的（`date`、`hash`、`json`、`pcre`、`reflection`、`filter`、`pcntl` 等默认就有），需要额外安装的是：

1  sudo apt install \
2    php8.5-mbstring \
3    php8.5-curl \
4    php8.5-intl \
5    php8.5-xml \
6    php8.5-bcmath \
7    php8.5-fileinfo \
8    php8.5-iconv \
9    php8.5-sockets 

🎵 使用感受是爽飞！ 🚀

#music-dl 是什么

一个开源的命令行音乐搜索下载器，支持腾讯、网易、酷狗等平台，PHP 编写，作者是 guanguans。

安装方式有两种：

方式一：直接下载预编译的 phar 文件（推荐）

1curl 'https://raw.githubusercontent.com/guanguans/music-dl/master/builds/music-dl' \
2  -o ~/.local/bin/music-dl --progress-bar
3chmod +x ~/.local/bin/music-dl

方式二：通过 Composer 安装

1composer global require guanguans/music-dl:dev-master --dev -v --ignore-platform-req=ext-pcntl

这里的 --ignore-platform-req=ext-pcntl 是因为 ext-pcntl 是 Linux 专属的进程控制扩展，macOS / Windows 原生环境没有，加这个参数强制跳过检查。

#为什么要用 WSL

music-dl 要求 PHP >= 8.5，且用到了 ext-pcntl（Linux 专属扩展），在 Windows 原生环境运行会遇到两个问题：

1. Windows 版 PHP 没有 pcntl 扩展，运行时报错
2. phar 文件依赖 shebang（#!/usr/bin/env php），Windows 不识别

所以直接在 WSL（Linux 子系统）里跑是最省心的方案。

#坑一：Ubuntu 24.04 默认源没有 PHP 8.5

WSL 里默认是 Ubuntu 24.04 (noble)，先查一下可用版本：

1apt-cache policy php-cli

输出：

1php-cli:
2  Installed: (none)
3  Candidate: 2:8.3+93ubuntu2

默认源只有 PHP 8.3，达不到 music-dl 要求的 8.5。

#坑二：mise 装 PHP 需要本地编译

试了用 mise（类似 uv / Scoop 的运行时版本管理工具）来装：

1mise install [email protected]

结果报错：

1buildconf: autoconf not found.
2You need autoconf version 2.68 or newer installed

原因是 mise 的 PHP 插件（基于 asdf-php）没有预编译二进制，需要从源码本地编译，得先装一堆系统级编译依赖：

1sudo apt install -y autoconf build-essential pkg-config libxml2-dev ...

太麻烦，放弃。

#解决方案：添加 ondrej/php PPA

ondrej/php 是 Ubuntu 社区用了十几年的 PHP 第三方源，维护者是官方认可的 PHP 打包者，安全可靠。

1sudo add-apt-repository ppa:ondrej/php
2# 看到确认提示，按 Enter 继续（不是 Ctrl+C！）
3sudo apt update
4sudo apt install php8.5-cli

⚠️ 注意：add-apt-repository 执行过程中会有一段等待，显示 PPA 信息后需要按 Enter 确认，不要以为卡住了就 Ctrl+C。整个过程根据网络情况可能需要等几分钟。

验证安装：

1php -v
2# PHP 8.5.x (cli)

#安装 music-dl

PHP 装好后，下载 phar 文件：

1mkdir -p ~/.local/bin
2curl 'https://raw.githubusercontent.com/guanguans/music-dl/master/builds/music-dl' \
3  -o ~/.local/bin/music-dl --progress-bar
4chmod +x ~/.local/bin/music-dl

确保 ~/.local/bin 在 PATH 里（一般 Ubuntu 默认已有）：

1echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
2source ~/.bashrc

运行：

1music-dl music "周杰伦"

#几个概念顺手整理

Composer 是什么

PHP 的依赖管理工具，相当于 Node.js 的 npm、Python 的 pip、.NET 的 NuGet。包托管在 Packagist。

phar 是什么

PHP Archive，PHP 的单文件可执行包，类似 Python 的 zipapp。把整个应用和依赖打包成一个文件，直接 php xxx.phar 运行。

为什么不用 Composer 全局安装

可以用，全局安装后 ~/.composer/vendor/bin 加入 PATH 即可直接调用。卸载也简单：

1composer global remove guanguans/music-dl

但全局安装有潜在的依赖冲突风险（多个工具依赖同一库的不同版本），对于独立 CLI 工具，直接用 phar 更干净。

#总结

最终选择：WSL + ondrej PPA 装 PHP 8.5 + phar 直接运行，简单干净。