phpMyAdmin 在 Vagrant 中打不开的根本原因是配置未正确启用或依赖缺失

简单来说，问题通常出在几个关键环节没打通：需要手动启用 Web 服务器的配置、确保 PHP 扩展（比如 mysqli 和 mbstring）与当前版本匹配、将自定义配置写入正确的文件（/etc/phpmyadmin/config.local.php），并且在同步配置时，只挂载 /etc/phpmyadmin/ 目录并设置好权限。对了，最后别忘了检查一下 session 目录的权限。

phpMyAdmin 在 Vagrant 中打不开：常见 404 或 500 错误

遇到页面打不开，十有八九是根儿上的路径或服务配置没生效。很多人以为在 Vagrant 里执行了 apt install phpmyadmin 就万事大吉，其实不然。尤其是在 Ubuntu 或 Debian 这类系统里，这个命令只是把文件解压到了 /usr/share/phpmyadmin 目录下，并不会自动为 Apache 或 Nginx 创建并启用对应的配置文件。结果就是，Web 服务器根本不知道去哪儿找 phpMyAdmin，404 错误自然就来了。

• 手动启用配置（针对 Apache）：执行 sudo ln -sf /etc/phpmyadmin/apache.conf /etc/apache2/conf-enabled/phpmyadmin.conf 创建软链接，然后别忘了 sudo systemctl reload apache2 重启服务让配置生效。
• 如果用的是 Nginx：情况就稍微复杂点，不能直接用 Apache 的配置。你需要自己编写一个 location /phpmyadmin 配置块，指向 /usr/share/phpmyadmin 这个物理路径，并且确保 fastcgi_pass 指令正确指向了 PHP-FPM 的 socket 文件（例如 unix:/run/php/php8.1-fpm.sock）。
• 还有一个隐蔽的坑：检查一下 /etc/phpmyadmin/config-db.php 这个文件是否存在且可读。如果安装过程中跳过了数据库配置步骤，这个文件可能会缺失，直接导致 500 内部服务器错误。

同步宿主机代码到 phpMyAdmin 的 config.inc.php

开发时，我们常常希望把在本机修改好的配置文件自动同步到 Vagrant 虚拟机里。但这里有个常见的误区：直接挂载整个 /usr/share/phpmyadmin 目录。这么做风险很高，会覆盖掉系统包管理器管理的文件，将来升级 phpMyAdmin 时很可能失败，还可能引发权限混乱。

• 更稳妥的做法是只同步配置文件：在 Vagrantfile 里，使用类似下面的配置，只将宿主机的特定目录同步到虚拟机的 /etc/phpmyadmin/：
  config.vm.synced_folder "./configs/phpmyadmin/", "/etc/phpmyadmin/", owner: "root", group: "root", mount_options: ["dmode=755,fmode=644"]
• 权限设置是关键：上面的 fmode=644 以及 owner/group="root" 必须指定。因为 phpMyAdmin 运行时是以 www-data 用户的身份去读取配置文件的，如果权限不对，Apache 或 Nginx 就无法读取，配置也就白费了。
• 另一种思路：使用符号链接：你也可以选择用 ln -sf /vagrant/configs/phpmyadmin/config.inc.php /etc/phpmyadmin/config.inc.php 创建软链接。但要注意，确保这个命令在 /vagrant 挂载点就绪之后才执行。因此，更推荐把它放在 vagrant up 之后运行的 shell 类型 provision 脚本里，而不是依赖 file 同步方式。

PHP 版本不匹配导致登录页空白或报 “mysqli extension missing”

phpMyAdmin 对 PHP 扩展的依赖比较严格，特别是 mysqli 和 mbstring。如果你使用的 Vagrant 基础镜像预装了 PHP 8.2，但通过 apt 安装的 phpMyAdmin 包却是为 PHP 7.4 构建的，那么扩展加载失败几乎是必然的。这时候，错误日志里可能只会留下一句冰冷的 PHP Fatal error: Uncaught Error: Call to undefined function mysqli_connect()，而页面上却一片空白，让人无从下手。

• 首先，确认 PHP 版本一致性：分别运行 php -v（命令行接口）和通过 Web 访问一个包含 phpinfo() 的测试页面，确保两者使用的 PHP 版本是相同的。
• 安装对应版本的扩展：根据确定的 PHP 版本，安装正确的扩展包，例如：sudo apt install php8.2-mysql php8.2-mbstring php8.2-xml（请将 8.2 替换为你的实际版本）。
• 处理扩展冲突：如果系统里存在多个 PHP 版本的扩展，可能需要手动禁用旧版本的配置（例如找到 /etc/php/7.4/mods-a vailable/mysqli.ini 并处理），或者直接使用 sudo phpdismod mysqli 命令来禁用冲突模块。

Vagrant reload 后 phpMyAdmin 配置丢失？检查 /etc/phpmyadmin/config.local.php

是不是遇到过这种情况：明明配好了数据库连接，一次 vagrant reload 之后，设置又恢复原样了？很多教程会指导你直接修改 /etc/phpmyadmin/config.inc.php 文件，比如在里面硬编码 $cfg['Servers'][1]['host'] = '192.168.33.10'。但问题是，这个文件属于系统包管理范围，当你执行 dpkg-reconfigure phpmyadmin 或系统升级时，它很可能被覆盖掉。

真正应该存放自定义配置的地方是 /etc/phpmyadmin/config.local.php。这个文件被主配置文件 config.inc.php 通过 include_once 显式引入，而且不受包管理器管控，是你的“自留地”。

• 所有自定义配置都应移至此文件：无论是修改 $cfg['blowfish_secret']、切换认证方式，还是指定特定的 MySQL 主机地址，都建议写在 config.local.php 里。
• 该文件可能需要手动创建：它默认并不存在，需要你手动创建，并确保其文件权限设置为 644，属主为 root:root。
• 注意版本控制安全：如果你使用了 synced_folder 同步整个 /etc/phpmyadmin/ 目录，切记将 config.local.php 添加到 .gitignore 等忽略文件中，避免将包含敏感信息（如密码）的配置文件提交到代码仓库。

最后，还有一个极其容易被忽略的细节：phpMyAdmin 的 session 存储路径（通常是 /var/lib/phpmyadmin/tmp）。在 Vagrant 重启后，由于 /tmp 类目录可能基于 tmpfs 内存文件系统而被清空，会导致 session 失效，表现为反复跳转到登录页面。解决办法是在 provision 脚本中，确保这个目录存在，并且权限正确（例如，属主设为 www-data:www-data，权限设为 1733）。