跳转到主要内容

​
简介

Laravel 框架的所有配置文件都存放在 config/ 目录下。每个选项都带有注释，可以打开文件查看可用的选项。 配置文件用来管理数据库连接信息、邮件服务器信息、应用 URL 与加密密钥等各种核心设置。

​
about 命令

使用 about Artisan 命令可以查看应用的配置、驱动与环境的概要。 
php artisan about
若只想查看特定部分，可使用 --only 选项。 
php artisan about --only=environment
若要详细查看某个配置文件的内容，可以使用 config:show 命令。 
php artisan config:show database

​
环境配置（.env）

在实际开发中，我们经常希望根据运行环境切换配置值。比如本地和生产环境使用不同的缓存驱动。 Laravel 借助 DotEnv PHP 库来简化这件事。全新安装时，应用根目录会包含一个 .env.example 文件（其中定义了常见的环境变量），安装过程会自动将其复制为 .env。
团队协作时，建议随代码维护 .env.example 并放在仓库中。写好占位值，可以让团队其他成员清楚地知道需要哪些环境变量。

​
环境文件的安全性

请不要把 .env 文件提交到版本控制。每位开发者与每台服务器所需的配置不同，且一旦泄露仓库将带来安全事故风险。
不过，Laravel 内置了加密环境文件的功能，加密后就可以安全地保存到版本控制中。

​
额外的环境文件

在应用启动时，Laravel 会检查是否指定了 APP_ENV 环境变量或 CLI 的 --env 参数。若已指定且存在 .env.[APP_ENV] 文件，则会加载该文件；否则使用默认的 .env。

​
环境变量的类型

.env 文件中的变量都会被解析为字符串，但为了让 env() 函数能够返回更丰富的类型，有以下特殊值：
.env 中的值env() 返回值
true(bool) true
(true)(bool) true
false(bool) false
(false)(bool) false
empty(string) ''
(empty)(string) ''
null(null) null
(null)(null) null
要设置包含空格的值，请使用双引号。 
APP_NAME="My Application"

​
读取环境变量

.env 中的所有变量在收到请求时会被加载到 PHP 超全局变量 $_ENV 中。在配置文件中可以通过 env() 函数获取。 
'debug' => (bool) env('APP_DEBUG', false),
第二个参数是默认值，当环境变量不存在时返回。

​
判断当前环境

当前环境由 .env 中的 APP_ENV 变量决定，可以通过 App 门面的 environment 方法获取。 
use Illuminate\Support\Facades\App;

$environment = App::environment();
也可以传入参数来判断是否处于某个环境。 
if (App::environment('local')) {
    // 本地环境
}

if (App::environment(['local', 'staging'])) {
    // 本地或 staging 环境
}

​
加密环境文件

未加密的环境文件不应保存到版本控制中，但 Laravel 提供了加密环境文件的功能。 
php artisan env:encrypt
执行后 .env 会被加密，密文保存到 .env.encrypted 中。解密密钥会在命令输出中展示，请存放到安全的密码管理器中。 解密使用 env:decrypt 命令。 
php artisan env:decrypt

​
访问配置值

可以通过 Config 门面或全局的 config() 函数在应用的任意位置访问配置值。使用「点号记法」，将文件名与选项名组合起来。 
use Illuminate\Support\Facades\Config;

$value = Config::get('app.timezone');

// 也可以用全局函数获取
$value = config('app.timezone');

// 指定不存在时的默认值
$value = config('app.timezone', 'Asia/Tokyo');
要在运行时更改配置值，可以使用 Config::set()，或者向 config() 传入数组。 
Config::set('app.timezone', 'America/Chicago');

config(['app.timezone' => 'America/Chicago']);
也提供了带类型的取值方法，若类型不匹配会抛出异常。 
Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');
Config::collection('config-key');

​
缓存配置

要提升应用性能，可以将所有配置文件缓存到单个文件中。 
php artisan config:cache
该命令会将所有配置选项汇总到一个文件里，使框架能更快地读取。
config:cache 命令应作为生产环境部署流程的一部分执行。本地开发过程中配置经常变动，不建议使用。
一旦生成了缓存，.env 文件在框架请求或运行 Artisan 命令时就不会再被加载。因此 env() 只会返回系统级环境变量。
正因如此，请务必只在 config/ 目录下的配置文件中使用 env()。应用其他地方获取配置请使用 config()。
要清除缓存，请使用 config:clear。 
php artisan config:clear

​
发布配置文件

Laravel 大多数配置文件都已经放在 config/ 目录中，但 cors.php、view.php 等文件默认并未发布。 要发布尚未发布的配置文件，使用 config:publish 命令。 
php artisan config:publish

php artisan config:publish --all

​
调试模式

config/app.php 中的 debug 选项决定错误信息要展示给用户多少。该选项默认跟随 .env 中的 APP_DEBUG 环境变量。
生产环境请务必将 APP_DEBUG 设置为 false。 若保持 true，可能会将应用敏感配置暴露给终端用户。
# 本地开发
APP_DEBUG=true

# 生产环境
APP_DEBUG=false

​
维护模式

当应用处于维护模式时，所有请求都会显示自定义视图。这样在升级或维护期间可以临时「关闭」应用。

​
启用维护模式

php artisan down
指定 --refresh 选项可以让浏览器在指定秒数后自动刷新。 
php artisan down --refresh=15
--retry 选项会设置为 Retry-After HTTP 头的值。 
php artisan down --retry=60

​
绕过维护模式

若希望通过秘密令牌允许特定用户访问，使用 --secret 选项。 
php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"
使用 --with-secret 选项则由 Laravel 自动生成令牌。 
php artisan down --with-secret

​
多服务器下的维护模式

默认情况下 Laravel 以文件方式管理维护模式。多服务器场景下，建议改用基于缓存的方式。 
APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

​
预渲染维护视图

若在部署过程中执行 php artisan down，可能会有用户在依赖更新过程中看到错误。可以使用 --render 选项预先渲染视图，避免这种情况。 
php artisan down --render="errors::503"
也可以将维护期间的所有请求重定向到指定 URL。 
php artisan down --redirect=/

​
关闭维护模式

php artisan up
可通过创建 resources/views/errors/503.blade.php 来自定义维护模式的默认模板。
如果希望完全消除停机时间，可以考虑 Laravel Cloud 这类全托管平台。

​
下一步

路由

学习将 URL 与控制器绑定的路由基础。
最后修改于 2026年7月13日

相关主题

WebSocket (Jetstream / Firehose)哈希（Hashing）Labeler日志密码重置