# 7.2 上传配置详解

:::tip 概述
文件上传配置定义在 `config/file.php` 和 `.env` 中，控制上传目录、访问域名、大小限制、允许的文件类型等。所有值通过 `env()` 函数从 `.env` 读取，支持多环境切换；`config/file.php` 中的注释明确标注了每个配置的**读取方**。
:::

## 配置文件

```php
// config/file.php — 文件上传配置（来自项目实际代码，节选）
return [
    // 文件上传根目录（相对 public），所有上传文件均存放于此
    // 读取方：UploadController::uploadFile()、save_file()、save_remote_file()
    'upload_dir' => env('FILE_UPLOAD_DIR', 'uploads'),

    // 文件访问域名，用于拼接完整 URL；为空时返回相对路径
    // 读取方：get_file_url()、save_content()、processContentFieldsOnRead()
    'domain_url' => env('FILE_DOMAIN_URL', ''),

    // 临时文件目录名（相对 upload_dir）
    // 读取方：UploadController::uploadFile()（上传落盘目录）、save_file()（识别 temp/ 开头的临时文件后迁移到正式目录）
    'temp_dir' => 'temp',

    // 允许上传的图片后缀（逗号分隔）
    // 安全说明：svg 已移除，因其可内嵌 JavaScript 导致 XSS 风险
    'image_ext' => env('FILE_IMAGE_EXT', 'gif,jpg,jpeg,png,bmp,webp'),

    // 允许上传的文件后缀（逗号分隔）
    'file_ext' => env('FILE_EXT', 'gif,jpg,jpeg,png,bmp,webp,doc,docx,xls,xlsx,ppt,pptx,pdf,zip,rar,txt,csv'),

    // 单文件最大尺寸（MB），转换为字节存储
    'max_size' => (int) env('FILE_MAX_SIZE', 10) * 1024 * 1024,
];
```

## 配置项详解

| 配置项 | .env 变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| `upload_dir` | `FILE_UPLOAD_DIR` | `uploads` | 上传根目录（**相对 `public/`**），所有文件存储于此 |
| `domain_url` | `FILE_DOMAIN_URL` | （空） | 文件访问域名，用于拼接完整 URL |
| `temp_dir` | — | `temp` | 临时目录名（相对 upload_dir），上传接口的落盘目录，`save_file()` 据此识别待迁移文件 |
| `image_ext` | `FILE_IMAGE_EXT` | `gif,jpg,jpeg,png,bmp,webp` | 图片允许后缀（**无 svg**） |
| `file_ext` | `FILE_EXT` | 图片+文档+压缩包等 | 文件允许后缀 |
| `max_size` | `FILE_MAX_SIZE` | `10` | 单文件最大大小（MB，配置内自动转字节） |

### upload_dir — 上传根目录

```ini
# .env
FILE_UPLOAD_DIR=uploads
```

**要求：**

- 本项目为**相对 `public/` 的目录**，Web 可直接访问其中的静态文件
- 目录必须存在且有写入权限（Docker 镜像已创建并授权 `public/uploads`）
- 上传文件随项目目录持久化（Docker 下即宿主机目录，不依赖命名卷）

**各环境示例：**

| 环境 | 值 | 实际位置 |
|------|------|---------|
| 本地开发 | `uploads` | `项目/public/uploads/` |
| Linux 生产 | `uploads`（或绝对路径） | Nginx root 下可直接访问 |
| Docker | `uploads` | 挂载的项目目录内 |

### domain_url — 文件访问域名

```ini
# .env
FILE_DOMAIN_URL=https://cdn.example.com
```

**要求：**

- 不要以 `/` 结尾（读取方会 `rtrim` 处理，但配置时保持规范）
- 必须是前端可访问的域名
- 本地开发可留空（接口返回相对路径，由同源/Vite 代理直接访问）

**各环境示例：**

| 环境 | 域名示例 |
|------|---------|
| 本地开发 | （留空，使用相对路径） |
| 虚拟域名开发 | `http://file.laravel13.elevue` |
| 测试环境 | `https://test-cdn.example.com` |
| 生产环境 | `https://cdn.example.com` 或对象存储域名 |

### temp_dir — 临时目录

```php
// config/file.php
'temp_dir' => 'temp',
```

**说明：**

- 上传接口 `uploadFile` 把文件写入 `{upload_dir}/temp/Ymd/`，不直接落正式目录
- `save_file()` / `save_content()` 依据 `temp/` 前缀把文件迁移到 Service 的 `fileSaveDir` 子目录
- 正式目录未被表单引用的临时文件可按周期清理（见下方「问题 4」）

### max_size — 文件大小限制

```ini
# .env（单位 MB，config 内 ×1024×1024 转字节）
FILE_MAX_SIZE=10
```

**建议值：**

| 场景 | 建议值 | 说明 |
|------|--------|------|
| 头像上传 | 2 MB | 图片通常不会太大 |
| 文章封面 | 5 MB | 压缩后的图片 |
| 通用文件上传 | 10 MB | 默认值 |
| 文档上传 | 20 MB | PDF/Word 等 |

:::warning 双层限制
业务层限制生效前，PHP 层必须放行：`php.ini` 的 `upload_max_filesize` / `post_max_size` 需 **大于等于** `FILE_MAX_SIZE`（建议 50M）。
:::

### image_ext / file_ext — 后缀白名单

```ini
# .env
FILE_IMAGE_EXT=gif,jpg,jpeg,png,bmp,webp      # uploadFile?type=image 校验
FILE_EXT=gif,jpg,jpeg,png,bmp,webp,doc,docx,xls,xlsx,ppt,pptx,pdf,zip,rar,txt,csv   # uploadFile（默认 type=file）校验
```

**说明：**

- `image_ext` 用于 `type=image`，只允许图片格式；**svg 已移除**（内嵌 JS 的 XSS 风险）
- `file_ext` 用于 `type=file`，允许图片、文档、压缩包等常见格式
- 白名单为空数组时跳过校验（防御性兜底），生产环境务必保留非空配置

## .env 配置示例

```ini
# 开发环境
FILE_UPLOAD_DIR=uploads
FILE_DOMAIN_URL=
FILE_MAX_SIZE=10

# 生产环境（示例）
FILE_UPLOAD_DIR=uploads
FILE_DOMAIN_URL=https://cdn.example.com
FILE_MAX_SIZE=10
FILE_IMAGE_EXT=gif,jpg,jpeg,png,bmp,webp
FILE_EXT=gif,jpg,jpeg,png,bmp,webp,doc,docx,xls,xlsx,pdf,zip,rar
```

## 目录结构

```text
public/
└── {upload_dir}/                        # upload_dir（默认 uploads）
    ├── temp/                            # 临时目录（UploadController 上传落盘）
    │   └── 20261002/
    │       └── 123456_a1b2c3d4e5f6.jpg
    ├── article/                         # 正式目录（由 Service 的 fileSaveDir 配置）
    │   └── 20261002/
    │       └── 153052_9f8e7d6c5b4a.pdf
    ├── example/
    ├── user/
    │   └── avatar/
    └── file_template/
```

### 目录命名规则

| 目录 | 说明 | 来源 |
|------|------|------|
| `temp/` | 临时文件目录（上传接口落盘） | `config/file.php → temp_dir` |
| `{module}/` | 按模块的正式目录 | Service 的 `fileSaveDir`（未配置按模型名推导） |
| `{Ymd}/` | 日期子目录 | 自动创建 |
| `{His}_{random}.{ext}` | 时间+随机文件名 | 防冲突与可预测性 |

## 文件生命周期

```text
1. 前端上传 → POST /api/upload/uploadFile
   保存到: public/uploads/temp/20261002/123456_a1b2c3d4e5f6.jpg
   返回: filePath + fileUrl

2. 前端提交表单 → 携带 filePath
   POST /api/example/add { name: "测试", avatar: "temp/20261002/..." }

3. ExampleService::add() → processFileFieldsOnSave → save_file()
   temp/ → 迁移到 fileSaveDir（example/）后，正式目录相对路径入库
   （其它分支：去掉域名直接用；外部 URL → 下载保存）

4. ExampleService::detail() → processFileFieldsOnRead → get_file_url()
   相对路径 → 拼接 FILE_DOMAIN_URL
   example/20261002/...
   → https://cdn.example.com/example/20261002/...
```

## 与 Service 层的配合

```php
class ArticleService extends BaseTenantService
{
    use HasFileProcessing, /* 其他 Trait */;

    protected array $fileFields = ['cover'];
    protected string $fileSaveDir = 'article';
}
```

**实际路径映射：**

```text
配置：
  FILE_UPLOAD_DIR = uploads
  FILE_DOMAIN_URL  = https://cdn.example.com
  fileSaveDir      = article

结果：
  上传文件:     public/uploads/temp/20261002/xxx.jpg
  Service 归一化后入库: article/20261002/xxx.jpg
  前端显示:     https://cdn.example.com/article/20261002/xxx.jpg
```

## Nginx 配置

### 静态文件直接由 Nginx 返回

```nginx
# 项目方案：public/uploads 位于站点根内，location / 由 try_files 直接返回静态文件
location / {
    try_files $uri $uri/ /index.php?$query_string;
}
```

### 禁止上传目录执行 PHP

```nginx
# docker/nginx.conf 已内置：仅入口 index.php 可执行，其余 .php 一律 404
location ~ \.php$ {
    return 404;
}
```

### 禁止访问隐藏文件

```nginx
location ~ /\. {
    deny all;
}
```

## 常见问题

### 问题 1：上传提示"目录不可写"

**原因：** `public/uploads` 没有写入权限。

**解决：**

```bash
# Linux
chmod -R 755 public/uploads
chown -R www-data:www-data public/uploads

# Docker：镜像内已 chown（storage / bootstrap/cache / public/uploads）
```

### 问题 2：上传后图片不显示

**原因：** `FILE_DOMAIN_URL` 配置错误或与前端不同源。

**解决：**

1. 检查 `.env` 中 `FILE_DOMAIN_URL` 是否为前端可访问的地址（改后 `php artisan config:clear`）
2. 留空时用相对路径——确认前端与后端同源或经代理
3. 浏览器直接打开图片 URL 验证

### 问题 3：文件大小限制不生效

**原因：** PHP 层限制小于业务层。

**解决：**

```ini
; php.ini（修改后重启服务）
upload_max_filesize = 50M
post_max_size = 50M
max_execution_time = 300
```

### 问题 4：临时文件未清理

**原因：** 上传后未提交表单（或表单未引用）的文件停留在 `temp/`，不会被迁移。

**解决：** 定期清理 `temp/` 中超过 1 天的文件：

```bash
# 定时任务：每天凌晨清理 1 天前的临时文件
find public/uploads/temp/ -type f -mtime +1 -delete
```

## 安全建议

| 建议 | 说明 |
|------|------|
| 扩展名白名单 | 只允许已知安全的文件类型（`FILE_IMAGE_EXT`/`FILE_EXT`） |
| 移除高危后缀 | svg 已移除；生产白名单去掉 `sql/js/css` 等可执行类 |
| MIME 类型检查 | 导入等场景配合 `finfo` 检测真实 MIME（见 [7.4 数据导入导出](/zh/tools/excel.html)） |
| 随机文件名 | 服务端生成（时间+随机串），防止路径遍历和文件名注入 |
| 文件大小限制 | `FILE_MAX_SIZE` 防止大文件 DoS |
| Nginx 禁止执行 PHP | 仅入口 `index.php` 可执行（Docker 配置已内置） |
| 定期清理临时文件 | `temp/` 内未被引用的文件按周期清理，避免磁盘空间被占满 |