Laravel: Laravel安装与配置详解

Q: 修改 .env 后需要重启服务器吗？

需要。php artisan serve 会自动重载，但 php-fpm 需要 php artisan config:clear 或重启服务。执行了 config:cache 的生产环境需重新 cache。

Q: config:cache 后修改了 .env 怎么生效？

运行 php artisan config:cache 重新生成缓存即可。它会重新读取 .env 和所有 config 文件，生成新的缓存文件。

最后更新：2026-08-26

配置是 Laravel 的"控制面板"——搞懂 .env 和 config/ 的关系，就像拿到了汽车的仪表盘，随时调节引擎参数。

1. 你将学到

.env 环境文件与 config/*.php 配置加载机制
环境切换：local/staging/production 配置策略
数据库连接配置（MySQL & PostgreSQL）
缓存与 Session 驱动配置
php artisan config:cache 生产环境配置缓存

2. 一个运维的真实故事

(1) 痛点：开发环境配置混乱

Alice 在本地开发 ShopMetrics 时用 MySQL，但部署到 staging 服务器后数据库连不上——因为她把 DB_PASSWORD 硬编码在代码里，推到 Git 后被同事 Bob 的本地密码覆盖了。更糟的是，Charlie 不小心把生产环境的 APP_DEBUG=true 提交了上去，导致线上错误堆栈全部暴露给用户。三人花了 2 天才排查完所有配置问题。

(2) .env 配置的解法

Laravel 用 .env 文件隔离环境变量——本地、staging、生产各一份，代码中绝不硬编码敏感值。

BASH

# .env (local — never commit this file)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shopmetrics_local
DB_USERNAME=root
DB_PASSWORD=secret

APP_DEBUG=true

(3) 收益

Alice 用 .env 管理配置后，本地和线上互不干扰，APP_DEBUG 在生产环境自动关闭，Bob 再也不会踩到密码覆盖的坑。

3. 环境配置机制

Laravel 的配置系统分两层：.env 文件存环境变量，config/*.php 文件读取并组织这些变量。

graph TD
    A[.env file] -->|dotenv loads| B[$_ENV / $_SERVER]
    B -->|config reads| C[config/database.php]
    C -->|env helper| D["env('DB_HOST', 'localhost')"]
    D -->|fallback| E[Default value if not set]

(1) .env 文件详解

.env 文件位于项目根目录，使用 KEY=VALUE 格式，绝不提交到 Git。

规则	说明
格式	`KEY=VALUE`，等号两侧无空格
引号	含空格的值用引号：`APP_NAME="My App"`
注释	`#` 开头的行是注释
类型	所有值都是字符串，需在代码中手动转换类型
优先级	实际环境变量 > `.env` 文件值

(2) config 目录机制

config/ 下每个 PHP 文件返回一个配置数组，通过 env() 函数读取环境变量。

配置文件	用途
`app.php`	应用名称、时区、加密密钥、调试模式
`database.php`	数据库连接、迁移表名
`cache.php`	缓存驱动（file/redis/database）
`session.php`	Session 驱动和生命周期
`mail.php`	邮件服务配置
`filesystems.php`	文件存储驱动

▶ 示例：查看当前配置值

BASH

# Check a specific config value
php artisan tinker
# In tinker REPL:
config('app.name')
# => "Laravel"

config('database.default')
# => "mysql"

config('cache.default')
# => "file"

输出：

TEXT 📖 仅展示

# 命令执行成功

4. 数据库配置

(1) MySQL 配置

PHP

// config/database.php — 'mysql' connection
'mysql' => [
    'driver' => 'mysql',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', '3306'),
    'database' => env('DB_DATABASE', 'shopmetrics'),
    'username' => env('DB_USERNAME', 'root'),
    'password' => env('DB_PASSWORD', ''),
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
],

(2) PostgreSQL 配置

PHP

// config/database.php — 'pgsql' connection
'pgsql' => [
    'driver' => 'pgsql',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', '5432'),
    'database' => env('DB_DATABASE', 'shopmetrics'),
    'username' => env('DB_USERNAME', 'postgres'),
    'password' => env('DB_PASSWORD', ''),
    'charset' => 'utf8',
],

维度	MySQL	PostgreSQL
默认端口	3306	5432
JSON 支持	5.7+ 原生	原生且更强
全文搜索	基础	高级（tsvector）
扩展性	中	高（PostGIS 等）
适用场景	电商/内容	地理/分析

▶ 示例：配置 ShopMetrics 的 MySQL 连接

BASH

# .env — Configure MySQL for ShopMetrics
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shopmetrics
DB_USERNAME=shopmetrics_user
DB_PASSWORD=Str0ngP@ssw0rd!

# Create the database
mysql -u root -p -e "CREATE DATABASE shopmetrics;"
mysql -u root -p -e "CREATE USER 'shopmetrics_user'@'localhost' IDENTIFIED BY 'Str0ngP@ssw0rd!';"
mysql -u root -p -e "GRANT ALL PRIVILEGES ON shopmetrics.* TO 'shopmetrics_user'@'localhost';"
mysql -u root -p -e "FLUSH PRIVILEGES;"

# Test connection
php artisan db:show
# Database: shopmetrics | MySQL 8.x | Tables: 0

输出：

TEXT 📖 仅展示

# 命令执行成功

5. 缓存与 Session 驱动

(1) 缓存驱动对比

驱动	适用场景	性能	持久化
`file`	开发/小项目	慢	✅
`database`	无 Redis 时	中	✅
`redis`	生产环境	快	✅
`memcached`	高并发读取	快	❌
`array`	测试	极快	❌

(2) Session 驱动对比

驱动	适用场景	说明
`file`	开发	存储在 `storage/framework/sessions/`
`database`	中等规模	需创建 sessions 表
`redis`	生产	高性能，支持 TTL
`cookie`	轻量	加密后存客户端，限 4KB
`array`	测试	请求结束即消失

▶ 示例：配置 Redis 缓存和 Session

BASH

# .env — Configure Redis for cache and session
CACHE_DRIVER=redis
SESSION_DRIVER=redis

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

# Install Redis PHP extension
pecl install redis

# Test Redis connection
php artisan tinker
# Cache::put('test_key', 'hello', 60)
# => true
# Cache::get('test_key')
# => "hello"

输出：

TEXT 📖 仅展示

# 命令执行成功

6. 环境切换策略

(1) 多环境配置方案

方案	做法	优缺点
多 .env 文件	`.env.local` / `.env.staging` / `.env.production`	简单但需手动切换
CI/CD 注入	在部署脚本中设置环境变量	安全但需 CI 平台
Laravel Envoyer	服务器端 .env 管理	官方工具但付费

(2) 关键环境变量差异

变量	Local	Staging	Production
`APP_ENV`	local	staging	production
`APP_DEBUG`	true	true	false
`CACHE_DRIVER`	file	redis	redis
`SESSION_DRIVER`	file	redis	redis
`LOG_LEVEL`	debug	info	warning

▶ 示例：为不同环境准备 .env 文件

BASH

# .env.local (development)
APP_ENV=local
APP_DEBUG=true
DB_DATABASE=shopmetrics_dev
CACHE_DRIVER=file
LOG_LEVEL=debug

# .env.staging (staging server)
APP_ENV=staging
APP_DEBUG=true
DB_DATABASE=shopmetrics_staging
CACHE_DRIVER=redis
LOG_LEVEL=info

# .env.production (live server)
APP_ENV=production
APP_DEBUG=false
DB_DATABASE=shopmetrics
CACHE_DRIVER=redis
LOG_LEVEL=warning

输出：

TEXT 📖 仅展示

# 命令执行成功

7. 配置缓存

生产环境中，Laravel 可以将所有配置文件合并缓存成单个 PHP 文件，避免每次请求都读 .env 和解析 config/*.php。

▶ 示例：使用配置缓存命令

BASH

# Cache all config (production)
php artisan config:cache
# Configuration cached successfully!

# After caching, env() returns null — always use config()
# This is a common gotcha!

# Clear config cache
php artisan config:clear
# Configuration cache cleared!

# Check if config is cached
php artisan config:status
# Config is cached.

输出：

TEXT 📖 仅展示

# 命令执行成功

⚠️ 注意： 执行 config:cache 后，env() 函数在非配置文件中将返回 null。只在 config/*.php 中使用 env()，其他地方一律用 config()。

命令	作用	使用场景
`config:cache`	缓存配置	生产部署
`config:clear`	清除缓存	修改配置后
`config:show`	查看配置值	调试
`env`	查看 .env 值	开发时

8. 综合示例：ShopMetrics 完整环境配置

PHP

// ============================================
// Comprehensive: ShopMetrics complete .env config
// Covers: app, database, cache, session, mail, logging
// ============================================

// .env file for ShopMetrics (local development)
/*
APP_NAME=ShopMetrics
APP_ENV=local
APP_KEY=base64:generated-key-here
APP_DEBUG=true
APP_URL=http://localhost:8000

LOG_CHANNEL=stack
LOG_LEVEL=debug

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shopmetrics
DB_USERNAME=shopmetrics_user
DB_PASSWORD=Str0ngP@ssw0rd!

CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_CONNECTION=database

MAIL_MAILER=smtp
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=shopmetrics-uploads
*/

BASH

# After configuring .env, run these commands:
php artisan key:generate
php artisan config:clear
php artisan migrate
php artisan db:seed
php artisan serve

输出：

TEXT 📖 仅展示

Application key set successfully.
Configuration cache cleared!
Info: Using MySQL database: shopmetrics
Migration table created successfully.
Starting Laravel development server: http://127.0.0.1:8000

❓ 常见问题

Q env() 和 config() 有什么区别？

A env() 直接读取 .env 文件的环境变量；config() 读取 config/*.php 中组织好的配置值。生产环境执行 config:cache 后，env() 在非配置文件中返回 null，应始终使用 config()。

Q .env 文件要提交到 Git 吗？

A 绝对不要。.env 包含数据库密码、API 密钥等敏感信息。只提交 .env.example 作为模板，实际 .env 由运维在服务器上创建。

Q 修改 .env 后需要重启服务器吗？

A 需要。php artisan serve 会自动重载，但 php-fpm 需要 php artisan config:clear 或重启服务。执行了 config:cache 的生产环境需重新 cache。

Q 什么时候用 SQLite 什么时候用 MySQL？

A 学习和原型开发用 SQLite（零配置）；生产环境用 MySQL（并发、复制、备份等企业特性）；需要高级查询（全文搜索、GIS）时选 PostgreSQL。

Q APP_KEY 的作用是什么？

A APP_KEY 用于所有加密操作（Session 加密、密码重置令牌、CSRF 令牌等）。如果更换 APP_KEY，所有已加密的数据将无法解密。生产环境部署后不要更换。

Q config:cache 后修改了 .env 怎么生效？

A 运行 php artisan config:cache 重新生成缓存即可。它会重新读取 .env 和所有 config 文件，生成新的缓存文件。

📖 小节

Laravel 配置分两层：.env 存环境变量，config/*.php 组织配置值
env() 只在 config 文件中使用，其他地方一律用 config()
MySQL 适合电商场景，PostgreSQL 适合分析场景，SQLite 适合开发
生产环境推荐 Redis 作为缓存和 Session 驱动
APP_DEBUG 在生产环境必须设为 false
config:cache 提升性能，但缓存后 env() 在非配置文件中失效

📝 作业

基础题（⭐）：配置 ShopMetrics 项目使用 MySQL 数据库，修改 .env 文件中的数据库连接信息，运行 php artisan migrate 确认连接成功。
进阶题（⭐⭐）：分别创建 .env.local 和 .env.staging 两个环境配置文件，使用不同的数据库名和缓存驱动，编写一个切换脚本来快速切换环境。
挑战题（⭐⭐⭐）：研究 config:cache 的实现原理（阅读 Illuminate/Foundation/Console/ConfigCacheCommand.php），解释为什么缓存后 env() 会失效，以及如何安全地在生产环境使用配置缓存。

Web-Tutorial 技术团队

由多位开发者共同维护的编程教程平台。每篇教程由对应领域的开发者编写和审核，确保内容准确可靠。如发现任何问题，欢迎向我们反馈。

关于我们

Laravel: Laravel安装与配置详解

1. 你将学到

2. 一个运维的真实故事

(1) 痛点：开发环境配置混乱

(2) .env 配置的解法

(3) 收益

3. 环境配置机制

(1) .env 文件详解

(2) config 目录机制

▶ 示例：查看当前配置值

4. 数据库配置

(1) MySQL 配置

(2) PostgreSQL 配置

▶ 示例：配置 ShopMetrics 的 MySQL 连接

5. 缓存与 Session 驱动

(1) 缓存驱动对比

(2) Session 驱动对比

▶ 示例：配置 Redis 缓存和 Session

6. 环境切换策略

(1) 多环境配置方案

(2) 关键环境变量差异

▶ 示例：为不同环境准备 .env 文件

7. 配置缓存

▶ 示例：使用配置缓存命令

8. 综合示例：ShopMetrics 完整环境配置

❓ 常见问题

📖 小节

📝 作业

🙏 帮我们做得更好