phpMyAdmin手动安装关键卡点在配置文件生成和PHP扩展依赖：需确保PHP≥7.4并启用mysqli、mbstring、json、zip、gd扩展；必须通过setup页面生成config.inc.php，而非手写；同时检查session.save_path权限及MySQL用户授权。
phpmyadmin 的手动安装不是“下载解压就能用”，关键卡点在配置文件生成和 php 扩展依赖上。直接复制 config.sample.inc.php 并改几个变量，大概率会遇到登录失败、空白页或“配置文件现在需要绝密的短语密码”报错。
确认 PHP 环境是否满足最低要求
phpmyadmin 5.2+ 要求 PHP ≥ 7.4，且必须启用以下扩展：
- mysqli（不是 mysql，后者已废弃）
- mbstring（字符编码处理）
- json（API 和界面交互依赖）
- zip（导入导出压缩包功能）
- gd（验证码、图表渲染）
运行 php -m | grep -E "mysqli|mbstring|json|zip|gd" 检查缺失项。若缺 mysqli，常见原因是 PHP 配置里写了 extension=mysql.so —— 必须改成 extension=mysqli.so 并重启 Web 服务。
从 Git 克隆并生成可运行目录结构
官方源码仓库地址是https://gitcode.com/gh_mirrors/ph/phpmyadmin，但注意：
- 不要直接在 Web 根目录下 git clone，否则 .git 目录可能被 Web 访问，存在泄露风险
- 推荐做法：克隆到临时目录，再复制必要文件
git clone https://gitcode.com/gh_mirrors/ph/phpmyadmin /tmp/pma-src cd /tmp/pma-src composer install --no-dev yarn install --production cp -r . /var/www/html/phpmyadmin/
复制后删掉 /var/www/html/phpmyadmin/.git 和 /var/www/html/phpmyadmin/node_modules（后者体积大且运行时不需要）。
配置文件不能靠手写，必须用 setup 页面生成
很多人试图直接编辑config.inc.php，结果因数组索引错位、引号编码错误或 $i 初始化遗漏导致白屏。正确路径是：
- 在 phpmyadmin 目录下新建 config 子目录（权限设为 755）
- 访问 http://your-server/phpmyadmin/setup
- 点击“新建服务器”，填入：
-
host：数据库 IP（本地用localhost，Docker 容器间通信用宿主机网关或服务名） -
auth_type：选cookie（生产环境）或config（仅限本地调试） - 若选
cookie，必须设置blowfish_secret—— 页面会自动生成 32 字符随机串，别自己填 “123456”
config.inc.php，放到 phpmyadmin 根目录，然后立即删掉 config/ 目录（防止被重写或恶意访问）
常见报错与绕过陷阱
- 报错Cannot start session without errors：PHP 的 session.save_path 目录不可写，检查 php.ini 中该项指向路径的权限
- 登录页提示 Access denied for user 'root'@'localhost'：不是 phpmyadmin 配置问题，而是 MySQL 用户没授权，执行 CREATE USER 'pma'@'localhost' IDENTIFIED BY 'xxx'; GRANT ALL ON *.* TO 'pma'@'localhost'; 更安全
- 界面中文乱码或部分按钮不显示：确认 $cfg['DefaultLang'] = 'zh' 已设，且 Web 服务器返回头包含 Content-Type: text/html; charset=utf-8真正麻烦的从来不是下载或复制，而是 PHP 扩展状态、session 权限、MySQL 用户权限这三处——它们不出错，phpmyadmin 就能跑；其中任一环节松动，都会卡在登录前。
