29. PHP 文件包含

本节目标：掌握 include、require 及其 _once 变种的用法与区别，了解自动加载机制。

大型项目代码量庞大，把所有逻辑写在一个文件里不现实。PHP 的文件包含机制让你可以把代码拆分到多个文件中组织管理。

29.1 `include` 与 `require`

两者功能相同：在指定位置插入另一个文件的内容。区别只在报错级别：

require：文件不存在时产生 E_COMPILE_ERROR，脚本终止执行
include：文件不存在时产生 E_WARNING，脚本继续执行

<?php
// 引入公共头部（不存在也能继续）
include 'header.php';

// 引入数据库配置（必须存在）
require 'db_config.php';

// 继续执行业务逻辑...

Note

框架、配置文件等关键文件用 require，可选组件（如广告条、侧边栏）用 include。

29.2 `_once` 后缀的作用

include_once 和 require_once 会检查文件是否已被包含，避免重复定义导致的错误。

<?php
// functions.php 中定义了 helper() 函数
require_once 'functions.php';

// 另一个文件也引入了 functions.php
// 若再次用 require，会报"函数已定义"错误
// 用 require_once 则安全跳过
require_once 'functions.php';

helper(); // 正常执行

Tip

包含类定义、函数定义的文件，强烈建议使用 _once 版本。包含模板文件则不需要。

29.3 实际应用场景

公共页头与页脚

<?php
// header.php
?>
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>我的网站</title>
</head>
<body>
    <nav>
        <a href="/">首页</a>
        <a href="/about.php">关于</a>
    </nav>

<?php
// footer.php
?>
    <footer>
        <p>版权所有 &copy; 2026</p>
    </footer>
</body>
</html>

<?php
// index.php
require 'header.php';
?>
    <h1>欢迎来到首页</h1>
<?php
require 'footer.php';

共享变量配置

<?php
// config.php
return [
    "db_host"     => "localhost",
    "db_name"     => "myapp",
    "db_user"     => "root",
    "db_pass"     => "secret",
    "site_name"   => "我的博客",
    "items_per_page" => 10,
];

<?php
// 使用配置
$config = require 'config.php';
echo $config["site_name"];

Tip

require 可以接收被包含文件的返回值，常用来加载配置数组。

29.4 包含路径规则

PHP 按以下顺序查找被包含文件：

如果是绝对路径（如 /var/www/header.php），直接定位
如果是相对路径，先按 include_path 配置查找
最后在调用脚本所在目录和当前工作目录查找

<?php
// 设置自定义包含路径
set_include_path(get_include_path() . PATH_SEPARATOR . __DIR__ . '/libs');

// 现在可以直接包含 libs 下的文件
require 'MyClass.php';

29.5 自动加载（Autoload）

手动 require 每个类文件很繁琐。PHP 提供了 spl_autoload_register（详见第 18 章命名空间的自动加载，以及第 39 章 Composer 的 PSR-4 自动加载）：

<?php
// autoload.php
spl_autoload_register(function (string $class) {
    // 把命名空间分隔符转为目录分隔符
    $file = __DIR__ . '/src/' . str_replace('\\', '/', $class) . '.php';

    if (file_exists($file)) {
        require $file;
    }
});

假设目录结构：

src/
  Models/
    User.php
  Utils/
    Validator.php

<?php
// User.php
namespace Models;

class User {
    public function sayHello(): void {
        echo "Hello!";
    }
}

<?php
// index.php
require 'autoload.php';

use Models\User;

$user = new User();
$user->sayHello(); // 自动加载 src/Models/User.php

Note

PHP 8.0 起自动加载函数可以指定参数类型，配合命名空间是现代项目的标准做法。

29.6 安全风险：路径遍历

如果被包含的文件名来自用户输入，可能引发严重安全问题：

<?php
// 危险！用户可能传入 ../../../etc/passwd
$page = $_GET["page"] ?? "home";
include $page . ".php"; // 绝不建议这样做！

// 安全的做法：白名单限制
$allowed = ["home", "about", "contact"];
if (in_array($page, $allowed, true)) {
    include $page . ".php";
} else {
    include "home.php";
}

Note

永远不要把用户输入直接拼接到 include/require 中。使用白名单是最安全的方案。

来源：参考了 runoob「PHP 包含」、w3cschool「PHP 包含」等，改写后所得。

PHP 文件包含

29. PHP 文件包含

29.1 include 与 require

29.2 _once 后缀的作用

29.3 实际应用场景

公共页头与页脚

共享变量配置

29.4 包含路径规则

29.5 自动加载（Autoload）

29.6 安全风险：路径遍历

29.1 `include` 与 `require`

29.2 `_once` 后缀的作用