ZBlogCMS 安装出现数据库连接失败怎么处理

学完这篇你能得到什么：看完这篇，你能自己定位 ZBlogCMS（ZBlogPHP）安装时报「数据库连接失败 / 无法连接数据库」的原因，并把它改成能装的状态。

ZBlogPHP 安装第二步要求填数据库信息，填错任何一个字段都会报同一个错，所以关键不是乱试，而是按下面的顺序一条条排除。

第一步：先看清楚报错原文，把问题分个类

这一步要做的，是把 ZBlog 给的报错信息读完整，因为不同提示指向完全不同的原因。

安装时出错，页面顶部或红框里通常会出现类似下面的内容：

• Access denied for user 'xxx'@'localhost' (using password: YES)——用户名或密码不对。
• Unknown database 'xxx'——数据库名写错，或者数据库根本没建。
• Can't connect to MySQL server on 'localhost' (10061)——MySQL 服务没启动，或端口不对。
• No such file or directory（socket 相关）——地址写法问题。

把这段英文抄下来，后面的排查就有方向了。

注意：不要只看「连接失败」四个字就去改密码，很多情况下密码是对的，错的是地址写法或权限。

第二步：确认 MySQL 服务确实在运行

这一步要做的，是排除「数据库根本没开机」这种最常见也最冤的情况，做完你能确定服务端是不是活的。

Windows 下按 Win + R，输入 services.msc，在列表里找 MySQL 或 MySQL80、MariaDB，看「状态」列是不是「正在运行」。如果没有，右键选「启动」。

Linux / 宝塔面板下，在终端执行：

systemctl status mysqld
# 或
systemctl status mariadb

宝塔用户直接在面板首页看「MySQL」那一行是否显示运行中。

再确认端口有没有在监听：

netstat -tlnp | grep 3306

有输出说明 3306 端口正常监听；如果服务在跑但端口没有，可能是改过端口，去 MySQL 配置文件 my.cnf（Linux）或 my.ini（Windows）里搜 port= 确认实际端口，安装时要用这个端口。

第三步：用命令行亲自连一次，验证账号密码

这一步要做的，是在装 ZBlog 之前先确认「这套账号密码到底能不能连上」这个数据库。

在终端（Windows 用 CMD 或 PowerShell）执行：

mysql -h 127.0.0.1 -P 3306 -u 你的用户名 -p

回车后输入密码。能进入 mysql> 提示符，说明账号密码和网络都没问题；报 Access denied 就是密码或用户不对；报 Can't connect 就是服务或端口问题。

进去后顺手看一下库在不在：

SHOW DATABASES;

列表里必须有你准备填进 ZBlog 的那个数据库名。

注意：如果这一步连不上，别急着回到 ZBlog 安装页反复提交，先在这里把连接跑通，问题会简单很多。

第四步：逐字核对安装页的六个字段

这一步要做的，是把 ZBlog 安装表单里的每一项和实际环境对上，做完基本能直接装成功。

ZBlogPHP 安装页数据库部分的字段和填写要点：

• 数据库地址：本地数据库优先填 127.0.0.1，而不是 localhost。因为 localhost 在部分环境会走 socket 连接，容易出现 No such file or directory。
• 数据库端口：默认 3306。如果服务器改过端口（比如宝塔换成了 3307），必须同步改。
• 数据库名：必须是已经创建好的库名，ZBlog 不会替你建库。宝塔面板在「数据库」→「添加数据库」里创建。
• 数据库用户名 / 密码：用上面命令行验证过的那一套。密码里有 @、#、$ 等符号时，注意前后不要多复制空格。
• 数据表前缀：默认 zbp_ 即可，同一库装多个站时才需要改。

第五步：检查这个数据库用户有没有权限

这一步要做的，是确认账号不只是「能登录」，还对目标数据库有操作权限。

在 mysql> 里执行：

SHOW GRANTS FOR '你的用户名'@'localhost';

输出里应该能看到类似：

GRANT ALL PRIVILEGES ON `你的库名`.* TO '用户名'@'localhost'

如果只看到 USAGE，说明这个用户没有任何库权限，需要补授权：

GRANT ALL PRIVILEGES ON `你的库名`.* TO '你的用户名'@'localhost' IDENTIFIED BY '你的密码';
FLUSH PRIVILEGES;

注意：ZBlog 安装过程需要建表，权限至少要包含 SELECT、INSERT、UPDATE、DELETE、CREATE、DROP、ALTER、INDEX，只给查询权限一定装不上。

第六步：确认 PHP 的 mysqli 扩展已开启

这一步要做的，是排除「数据库没问题、但 PHP 连不上数据库」的情况。

在终端执行：

php -m | grep -i mysqli

没有任何输出，说明扩展没开。找到 php.ini（宝塔在「软件商店」→ PHP 版本 →「配置修改」里），把这一行前面的分号去掉：

extension=mysqli

保存后重启 PHP 服务。ZBlogPHP 依赖 mysqli，扩展缺失时会直接报连接失败。

第七步：MySQL 8 的认证方式问题

这一步要做的，是处理 MySQL 8.0 默认加密方式与老版本 PHP 不兼容导致的连接失败。

现象是命令行能连、ZBlog 连不上，或者报 The server requested authentication method unknown to the client。

解决办法是把该用户的认证插件改回兼容模式，在 mysql> 里执行：

ALTER USER '你的用户名'@'localhost' IDENTIFIED WITH mysql_native_password BY '你的密码';
FLUSH PRIVILEGES;

第八步：实在装不上，就手写配置文件

这一步要做的，是绕过安装向导，直接把数据库参数写进配置文件。

ZBlogPHP 的配置文件是站点根目录下的 c_option.php（老版本为 conf.php）。安装向导走不通时，可以先手动建库，再在文件里填好 ZC_DATABASE_* 系列常量，然后访问后台。这种方式适合数据库信息确认无误、但向导反复报错的场景。

小结

• 报错原文决定排查方向：Access denied 查账号密码，Unknown database 查库名，Can't connect 查服务和端口。
• 地址优先写 127.0.0.1 而不是 localhost，能避开 socket 相关的连接失败。
• 先用 mysql -h 127.0.0.1 -P 3306 -u 用户名 -p 在命令行验证一遍，连不上就别在安装页反复提交。
• 数据库必须提前建好，账号必须有建表权限，只给查询权限装不上。
• php -m | grep -i mysqli 没有输出就说明 PHP 扩展没开。
• MySQL 8 用户认证插件与老 PHP 不兼容时，改成 mysql_native_password。