先做裸连测试验证基础连通性，再检查hostname是否为127.0.0.1、mysqli扩展是否启用、.env权限及编码是否正确、cpanel中用户是否绑定数据库并授予必要权限。
遇到 Unable to connect to your database server using the provided settings 错误，别急着改 .env 或重装框架——90% 的情况，CI4 根本还没开始加载配置，错误就发生在 PHP 尝试建立 MySQL 连接的那一瞬间。先确认数据库能不能连上，再查框架有没有读到配置。
第一步：用裸连测试验证基础连通性
新建一个 test_db.php 文件，放在你的网站可访问目录（比如子域名根目录），内容如下：
<?php <br>$conn = mysqli_connect("localhost", "yourusername_dbuser", "yourpassword", "yourusername_dbname");<br>if (!$conn) {<br> die("连接失败: " . mysqli_connect_error());<br>}<br>echo "连接成功！";<br>mysqli_close($conn);<br>?>
访问这个文件，看是否报错。如果失败，说明问题出在：
- 数据库名或用户名漏了 Namecheap 强制添加的前缀（如
abc123_myapp，不是myapp） - 密码输错、大小写或特殊字符没转义
- 用户没和数据库关联（cPanel → MySQL Databases → Add User To Database）
- 权限没给够（至少 SELECT/INSERT/UPDATE/DELETE）
第二步：检查 hostname 和 PHP 扩展
Linux 共享主机上，localhost 默认走 Unix socket，但 PHP 可能找不到 /var/run/mysqld/mysqld.sock，报错 (HY000/2002): No such file or directory。换成 127.0.0.1 强制走 TCP/IP。
同时确认 mysqli 扩展已启用：
- 命令行运行：
php -m | grep -i mysqli - 注意：CLI 和 Web（如 Apache/FPM）可能加载不同 php.ini，别只信 phpinfo() 页面
第三步：确认 .env 配置被正确加载
CI4 依赖 .env 文件，但它必须满足三个条件才能生效：
-
.env文件权限为644（不能是 666 或 755） - 文件不能有 UTF-8 BOM 头（用 VS Code 或 Notepad++ 检查并转为“UTF-8 无 BOM”）
- 项目结构正确：核心目录（
app、system、.env）放在 Web 根目录之外，public/内容移到子域名根目录，并修改public/index.php中的$pathsPath指向真实路径
常见错误：把整个 CI4 项目直接扔进 public_html，导致 .env 被暴露且不被读取。
第四步：核对 cPanel 数据库授权细节
Namecheap 共享主机上，光建库、建用户还不够：
- 必须进入 cPanel →「MySQL Databases」→「Add User To Database」
- 手动将用户绑定到目标数据库
- 勾选权限时，不要只点「ALL PRIVILEGES」就跳过——有些主机限制该选项，稳妥做法是逐个勾选 SELECT、INSERT、UPDATE、DELETE、CREATE、DROP
没做这一步，即使裸连能通（比如用 root 用户），你的应用用户也照样被拒绝。
