要让Laravel项目在Windows和macOS上开箱即用，必须统一.env与.env.example双文件结构、严格大小写匹配变量名、设APP_URL为http://127.0.0.1:8000、敏感值仅从.env读取并运行php artisan key:generate生成密钥、每次切换平台后执行config:clear再config:cache。
要让 Laravel 项目在 Windows 和 macOS 上真正“开箱即用”，环境变量配置不能只靠 `.env` 文件填完就完事——它必须可移植、可复现、不依赖系统特性。核心是：统一管理结构、隔离敏感值、强制缓存刷新、适配路径与协议差异。
统一用 .env + .env.example 双文件结构
`.env` 不提交到 Git，但 `.env.example` 必须提交且保持字段完整。它不是示例，而是契约：
- 所有环境变量名（如 DB_HOST、APP_URL、TIMEZONE）必须一致，大小写严格匹配（macOS 区分大小写，Windows 不区分但 Laravel 内部全小写处理）
- 示例值用占位符，比如 DB_PASSWORD=your_db_password_here，而非空值或注释行
- 新增配置项（如 Redis 或 Mailgun）时，同步更新 `.env.example`，避免 Mac 开发者拉代码后因缺失变量导致 `config:cache` 失败
APP_URL 和 URL 生成逻辑必须对齐
跨平台最常见的 404 或资源加载失败，往往源于 `APP_URL` 配置不当或前端硬编码路径：
- 开发阶段统一设为 APP_URL=http://127.0.0.1:8000（不用 localhost，避免 macOS DNS 解析延迟）
- 若用 Laravel Sail/Docker，改用容器服务名，如 APP_URL=http://localhost（Nginx 映射到宿主机 80 端口）
- 所有前端资源链接必须用 asset()、route()、url() 生成，禁用
/css/app.css或http://localhost:8000/css/app.css这类硬写
敏感值不进代码，配置不靠系统差异
密码、密钥、API Token 等绝不能写死在配置文件或代码里，也不能通过系统环境变量注入（Windows 的 setx 与 macOS 的 .zshrc 行为不一致）：
- 只从 `.env` 读取，Laravel 的 env() 函数已自动处理类型转换和默认回退
- 生成密钥必须运行 php artisan key:generate，且确保 `.env` 中 APP_KEY 已写入——否则 Session、CSRF、加密全部失效，首页都打不开
- 部署时用 CI/CD 注入 `.env` 内容，或用 dotenv 封装工具（如 vlucas/phpdotenv v5+），它对 Windows 换行符（CRLF）和 macOS（LF）兼容性更好
每次切换平台或拉新代码后必清缓存
`.env` 修改后，Laravel 会缓存配置，而缓存文件（如 `bootstrap/cache/config.php`）在 Windows 和 macOS 上的权限模型不同，容易残留旧值：
- 执行 php artisan config:clear 删除缓存
- 再运行 php artisan config:cache（仅限生产环境）或跳过缓存直接开发
- 推荐开发阶段关闭配置缓存：APP_ENV=local 且不执行
config:cache，避免因缓存未更新导致行为不一致
