编程马·菜鸟教程

Appearance

第 18 章：新手常见错误与避坑 ​

18.1 页面空白、500 错误 ​

页面空白的原因 ​

1. PHP 语法错误 ​

php
<?php
// 错误：缺少分号
echo "Hello"
echo "World";

// 错误：括号不匹配
if ($condition {
    echo "条件为真";
}

// 错误：引号不匹配
echo "Hello World';
?>

2. 错误报告被关闭 ​

php
<?php
// 开启错误报告
error_reporting(E_ALL);
ini_set('display_errors', 1);

// 你的代码...
?>

3. PHP 文件编码问题 ​

php
<?php
// 确保文件编码为 UTF-8（无 BOM）
// 使用编辑器转换编码
?>

500 错误的原因 ​

1. 语法错误 ​

php
<?php
// 检查语法错误
// 使用 php -l filename.php 命令检查
?>

2. 内存不足 ​

php
<?php
// 增加内存限制
ini_set('memory_limit', '256M');
?>

3. 执行时间超时 ​

php
<?php
// 增加执行时间
set_time_limit(300); // 5 分钟
?>

调试方法 ​

php
<?php
// 开启所有错误报告
error_reporting(E_ALL);
ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);

// 检查错误日志
// 错误日志位置：php.ini 中的 error_log 设置
?>

18.2 数据库连接失败 ​

常见原因 ​

1. 数据库服务未启动 ​

bash
# Windows
net start mysql

# Linux
sudo service mysql start

2. 连接参数错误 ​

php
<?php
// 检查连接参数
$servername = "localhost";
$username = "root";
$password = "";
$dbname = "myDB";

$conn = mysqli_connect($servername, $username, $password, $dbname);

if (!$conn) {
    die("连接失败: " . mysqli_connect_error());
}
echo "连接成功";
?>

3. 数据库不存在 ​

php
<?php
// 先连接 MySQL 服务器
$conn = mysqli_connect("localhost", "root", "");

// 创建数据库
$sql = "CREATE DATABASE IF NOT EXISTS myDB";
if (mysqli_query($conn, $sql)) {
    echo "数据库创建成功";
} else {
    echo "创建失败: " . mysqli_error($conn);
}
?>

4. 用户权限不足 ​

sql
-- 授予用户权限
GRANT ALL PRIVILEGES ON myDB.* TO 'root'@'localhost';
FLUSH PRIVILEGES;

调试方法 ​

php
<?php
$conn = mysqli_connect("localhost", "root", "", "myDB");

if (!$conn) {
    // 输出详细错误信息
    echo "错误代码: " . mysqli_connect_errno() . "<br>";
    echo "错误信息: " . mysqli_connect_error() . "<br>";
    
    // 检查 MySQL 服务是否运行
    if (!function_exists('mysqli_connect')) {
        echo "MySQLi 扩展未安装";
    }
}
?>

18.3 表单数据接收不到 ​

常见原因 ​

1. 表单 method 属性错误 ​

html
<!-- 错误：method 拼写错误 -->
<form method="post">
    <input type="text" name="username">
    <button type="submit">提交</button>
</form>

<!-- 正确 -->
<form method="post">
    <input type="text" name="username">
    <button type="submit">提交</button>
</form>

2. input name 属性缺失 ​

html
<!-- 错误：缺少 name 属性 -->
<form method="post">
    <input type="text">
    <button type="submit">提交</button>
</form>

<!-- 正确 -->
<form method="post">
    <input type="text" name="username">
    <button type="submit">提交</button>
</form>

3. 表单 enctype 设置错误 ​

html
<!-- 上传文件时必须设置 enctype -->
<form method="post" enctype="multipart/form-data">
    <input type="file" name="file">
    <button type="submit">上传</button>
</form>

4. PHP 配置问题 ​

php
<?php
// 检查 PHP 配置
echo "post_max_size: " . ini_get('post_max_size') . "<br>";
echo "upload_max_filesize: " . ini_get('upload_max_filesize') . "<br>";
?>

调试方法 ​

php
<?php
// 打印所有接收到的数据
echo '<pre>';
print_r($_POST);
print_r($_GET);
print_r($_FILES);
echo '</pre>';

// 检查请求方法
echo "请求方法: " . $_SERVER['REQUEST_METHOD'] . "<br>";

// 检查原始数据
echo "原始 POST 数据: " . file_get_contents('php://input') . "<br>";
?>

18.4 乱码问题 ​

常见原因 ​

1. 文件编码问题 ​

php
<?php
// 确保文件编码为 UTF-8（无 BOM）
// 使用编辑器设置文件编码
?>

2. 数据库编码问题 ​

php
<?php
// 连接数据库时设置编码
$conn = mysqli_connect("localhost", "root", "", "myDB");
mysqli_set_charset($conn, "utf8mb4");

// 或者在 SQL 语句中设置
mysqli_query($conn, "SET NAMES utf8mb4");
?>

3. HTML 页面编码问题 ​

html
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>页面标题</title>
</head>
<body>
    <!-- 页面内容 -->
</body>
</html>

4. PHP 输出编码问题 ​

php
<?php
// 设置 PHP 输出编码
header('Content-Type: text/html; charset=utf-8');
?>

解决方案 ​

php
<?php
// 1. 设置 PHP 输出编码
header('Content-Type: text/html; charset=utf-8');

// 2. 连接数据库时设置编码
$conn = mysqli_connect("localhost", "root", "", "myDB");
mysqli_set_charset($conn, "utf8mb4");

// 3. 创建数据库时指定编码
$sql = "CREATE DATABASE myDB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci";

// 4. 创建表时指定编码
$sql = "CREATE TABLE users (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(50)
) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci";
?>

18.5 上传失败 ​

常见原因 ​

1. 文件大小超过限制 ​

php
<?php
// 检查 PHP 配置
echo "upload_max_filesize: " . ini_get('upload_max_filesize') . "<br>";
echo "post_max_size: " . ini_get('post_max_size') . "<br>";

// 修改配置（php.ini）
// upload_max_filesize = 10M
// post_max_size = 10M
?>

2. 临时目录不存在或无权限 ​

php
<?php
// 检查临时目录
echo "临时目录: " . ini_get('upload_tmp_dir') . "<br>";

// 检查目录权限
$temp_dir = ini_get('upload_tmp_dir') ?: sys_get_temp_dir();
if (is_writable($temp_dir)) {
    echo "临时目录可写";
} else {
    echo "临时目录不可写";
}
?>

3. 目标目录不存在或无权限 ​

php
<?php
$upload_dir = 'uploads/';

// 检查目录是否存在
if (!file_exists($upload_dir)) {
    mkdir($upload_dir, 0777, true);
}

// 检查目录权限
if (is_writable($upload_dir)) {
    echo "目录可写";
} else {
    echo "目录不可写";
    chmod($upload_dir, 0777);
}
?>

4. 文件类型限制 ​

php
<?php
// 检查错误码
if ($_FILES['file']['error'] !== UPLOAD_ERR_OK) {
    switch ($_FILES['file']['error']) {
        case UPLOAD_ERR_INI_SIZE:
            echo "文件大小超过 php.ini 中的限制";
            break;
        case UPLOAD_ERR_FORM_SIZE:
            echo "文件大小超过表单中的限制";
            break;
        case UPLOAD_ERR_PARTIAL:
            echo "文件只上传了一部分";
            break;
        case UPLOAD_ERR_NO_FILE:
            echo "没有文件被上传";
            break;
        case UPLOAD_ERR_NO_TMP_DIR:
            echo "缺少临时文件夹";
            break;
        case UPLOAD_ERR_CANT_WRITE:
            echo "文件写入失败";
            break;
    }
}
?>

18.6 登录失效 ​

常见原因 ​

1. Session 未启动 ​

php
<?php
// 必须在页面开头启动 Session
session_start();

// 检查 Session 是否启动
if (session_status() === PHP_SESSION_ACTIVE) {
    echo "Session 已启动";
}
?>

2. Session 配置问题 ​

php
<?php
// 检查 Session 配置
echo "session.save_path: " . session_save_path() . "<br>";
echo "session.cookie_lifetime: " . ini_get('session.cookie_lifetime') . "<br>";
echo "session.gc_maxlifetime: " . ini_get('session.gc_maxlifetime') . "<br>";

// 设置 Session 过期时间
ini_set('session.cookie_lifetime', 3600); // 1 小时
ini_set('session.gc_maxlifetime', 3600); // 1 小时
?>

3. Cookie 被禁用 ​

php
<?php
// 检查 Cookie 是否启用
if (isset($_COOKIE['test'])) {
    echo "Cookie 已启用";
} else {
    setcookie('test', '1');
    if (isset($_COOKIE['test'])) {
        echo "Cookie 已启用";
    } else {
        echo "Cookie 被禁用";
    }
}
?>

4. Session 被意外销毁 ​

php
<?php
// 检查 Session 是否被销毁
session_start();

if (isset($_SESSION['user_id'])) {
    echo "用户已登录";
} else {
    echo "用户未登录";
    // 检查是否调用了 session_destroy()
    // 检查是否清空了 $_SESSION
}
?>

调试方法 ​

php
<?php
session_start();

// 打印 Session 内容
echo '<pre>';
print_r($_SESSION);
echo '</pre>';

// 打印 Cookie 内容
echo '<pre>';
print_r($_COOKIE);
echo '</pre>';

// 检查 Session ID
echo "Session ID: " . session_id() . "<br>";
?>

小结 ​

通过本章的学习，你了解了 PHP 开发中常见的错误和问题，包括页面空白、500 错误、数据库连接失败、表单数据接收不到、乱码问题、上传失败和登录失效等。掌握这些问题的解决方法，可以帮助你快速定位和解决问题，提高开发效率。在实际开发中，遇到问题时应该先开启错误报告，查看错误信息，然后根据错误信息进行调试和修复。同时，养成良好的编码习惯，遵循最佳实践，可以减少很多常见错误的发生。

© 2026 编程马·菜鸟教程 版权所有

基于 VitePress 构建