PHP 模块化编程：include 与 require

Begindev 编辑部 March 25, 2026

PHP 应用程序通常由多个文件组成，以组织代码、分离关注点并提高可复用性。与其将所有代码塞进一个单一、庞大的文件中，开发者更倾向于将项目拆分为更小、更易于管理的单元。这种方法提高了代码的可读性，简化了维护工作，并允许应用程序的不同部分共享通用的功能、配置或前端模板。

1. include 语句

include 语句用于将另一个 PHP 文件的内容嵌入到当前文件中。当执行到 include 时，PHP 会在确切的调用位置处理指定的文件，就好像该文件的内容原本就写在那里一样。

1.1 include 的基本用法

要使用 include，你只需指定要包含的文件的路径即可。路径可以是相对于当前脚本的相对路径，也可以是绝对路径。

// included_file.php
<?php
$message = "来自 included_file.php 的问候！";

function greetUser($name) {
    return "欢迎你，" . $name . "！";
}
?>

// main_script.php
<?php
echo "主脚本开始运行...\n";

include 'included_file.php'; // 包含 included_file.php 的内容

echo $message . "\n"; // 现在可以访问 $message 变量了
echo greetUser("Alice") . "\n"; // 现在可以调用 greetUser() 函数了

echo "主脚本运行结束。\n";
?>

在这个例子中，一旦 include 语句执行完毕，main_script.php 就能立刻访问在 included_file.php 中定义的 $message 变量和 greetUser() 函数。

1.2 include 的错误处理机制

如果 include 指定的文件找不到或者存在访问权限问题，include 会生成一个警告级别错误 (E_WARNING)。在发出警告后，脚本会继续执行，尝试运行剩余的代码。这种特性在包含应用程序的非关键部分时非常有用，比如可选的侧边栏小部件或广告横幅，因为它们的缺失不应该导致整个页面的加载崩溃。

// main_script_with_warning.php
<?php
echo "尝试包含一个不存在的文件...\n";

include 'non_existent_file.php'; // 这将生成一个 E_WARNING

echo "脚本在警告后继续运行。这行代码仍然会执行。\n";
// 任何后续依赖 'non_existent_file.php' 的代码可能会报错，
// 但脚本本身并没有在这里停下。
?>

当找不到 non_existent_file.php 时，PHP 会发出警告，但 main_script_with_warning.php 仍然会输出“脚本在警告后继续运行...”。

1.3 include 的实际应用场景

页眉/页脚模板： 许多 Web 应用程序使用 include 在多个页面中插入公共的页眉（Header）和页脚（Footer）。这确保了网站外观风格的一致性，并将这些公共元素的 HTML 代码集中在一处管理。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>我的超赞网站</title>
</head>
<body>
    <header>
        <h1>欢迎来到我的网站</h1>
        <nav>
            <a href="/">首页</a>
            <a href="/about.php">关于我们</a>
        </nav>
    </header>
    <main>

</main>
    <footer>
        <p>© <?php echo date("Y"); ?> 我的超赞网站。保留所有权利。</p>
    </footer>
</body>
</html>

// index.php
<?php include 'header.php'; ?>
    <h2>首页内容</h2>
    <p>这是首页的主要内容区域。</p>
<?php include 'footer.php'; ?>

在这种结构下，index.php 只需要包含 header.php 和 footer.php，就能用可复用的组件拼装出一个完整的 HTML 页面。

配置文件： include 经常被用来引入配置设置，例如数据库凭证或 API 密钥。为了安全和便于管理，这些信息通常存储在单独的文件中。(注：虽然这里举例用 include，但在实际开发中，核心配置文件更推荐使用接下来要讲的 require)。

2. require 语句

require 语句同样用于将另一个 PHP 文件的内容嵌入到当前文件中。然而，require 在错误处理机制上有着决定性的不同。

2.1 require 的基本用法

require 的语法与 include 完全相同。

// common_functions.php
<?php
function calculateSum($a, $b) {
    return $a + $b;
}
?>

// application_entry.php
<?php
echo "正在加载应用...\n";

require 'common_functions.php'; // 包含 common_functions.php

echo "5 和 3 的和是: " . calculateSum(5, 3) . "\n";
echo "应用加载成功。\n";
?>

2.2 require 的错误处理机制

如果 require 指定的文件找不到或无法访问，require 会生成一个致命错误 (E_ERROR)。这个错误会立即停止脚本的执行。

这种行为非常适合用于包含脚本运行绝对必需的文件，例如核心类库、数据库连接文件或关键配置。如果这些文件丢失了，应用程序根本无法正常运作，此时立即中止执行，远比带着缺失的依赖继续强行运行（从而引发更多不可预知的连锁错误）要安全得多。

// application_critical.php
<?php
echo "尝试 require 一个不存在的关键文件...\n";

require 'critical_library.php'; // 这将生成一个 E_ERROR 并强制停止脚本

// 如果 critical_library.php 找不到，下面这行代码【绝对不会】被执行
echo "这行代码永远不会被到达。\n";
?>

2.3 require 的实际应用场景

核心库和框架文件：在大型应用或使用框架时，require 通常用于加载整个应用程序依赖的基础文件。例如，用于加载类的自动加载器脚本（Autoloader）。

// index.php (主入口文件)
<?php
require 'vendor/autoload.php'; // Composer 管理的依赖，不可或缺

// 假设 App\Core\Application 类必须被加载
$app = new App\Core\Application();
$app->run();
?>

如果 vendor/autoload.php 丢失了，应用程序将无法加载任何依赖类，继续执行毫无意义。require 确保了这一刚性依赖得到满足。

数据库连接文件： 建立数据库连接通常是大多数 Web 应用的先决条件。如果连接逻辑在单独的文件中，且该文件丢失，应用将彻底瘫痪。

// user_profile.php
<?php
require 'db_connect.php'; // 进行数据库操作的绝对前提

// 只有成功 require 后，$mysqli 对象才可用
$result = $mysqli->query("SELECT * FROM users WHERE id = 1");
?>

如果缺少 db_connect.php，强行执行后续的查询语句会导致一连串报错。require 充当了坚固的守门员。

3. include 与 require 的核心对比

根本的区别在于发生错误时的处理级别：

特性	include	require
错误级别	产生警告 `(E_WARNING)`	产生致命错误 `(E_ERROR)`
脚本执行流	抛出警告后，脚本继续向下执行。	抛出错误后，脚本立即强制终止。
适用场景	包含非关键性文件（如页眉/页脚模板、可选的 UI 组件等）。	包含决定程序生死存亡的关键文件（如核心库、配置文件、数据库连接等）。

经验法则：什么时候用哪个？

使用 include：即使被包含的文件丢失了，脚本依然能提供部分功能（哪怕体验降级）。比如丢失了一个侧边栏广告模块，但主体文章依然可以阅读。
使用 require：被包含的文件包含了脚本正确运行的绝对必要条件。如果丢失，程序就像失去了大脑，必须立刻停止运转以防止产生脏数据或更严重的安全漏洞。