# Phoenix 文件上传 ## 规则 — 毫无例外地遵守这些规则 1. **对表单提交模式使用手动上传（不是 auto_upload: true）** 2. **始终将上传目录添加到 static_paths()** — 没有此文件将无法访问 3. **处理上传错误** — 在模板中显示 error_to_string/1 输出 4. **在保存文件之前使用File.mkdir_p!**创建上传目录 5. **生成唯一的文件名** — 防止冲突和路径遍历攻击 6. **在服务器端验证文件类型** — 永远不要信任客户端 MIME 类型 7. **更改 static_paths() 后重新启动服务器** — 更改在重新启动之前不会应用 ** ** ## 上传配置 ### 手动上传（大多数情况下推荐）允许上传(:上传名称, 接受：~w(.jpg .jpeg .png .pdf), 最大条目数：10，最大文件大小：10_000_000 ） **模板要求：** * 带有“phx-submit”事件的表单 * 提交按钮触发上传 * `<.live_file_input>` 组件 * 进度指标 ### 自动上传（高级 - 谨慎使用）仅在以下情况下使用“auto_upload: true”： * 文件应在选择后立即上传 * 你有 `handle_progress/3` 回调 * 您在表单提交之外消耗了条目 **⚠️ 切勿将 auto_upload: true 与表单提交模式一起使用！** ## 完整的上传模式 ### 实时查看模块 @impl true def mount(_params, _session, socket) 做插座= 插座 |> 分配（：上传的文件，[]） |> 允许上传(:照片, 接受：~w(.jpg .jpeg .png), 最大条目数：5，最大文件大小：10_000_000 ） {：好的，套接字} 结束 @impl true def handle_event("validate", _params, socket) 做 {:norply, 套接字} 结束 @impl true def handle_event("保存", _params, socket) 做上传的文件= Consumer_uploaded_entries(socket, :photos, fn %{path: path}, 条目 -> dest = Path.join(["priv", "static", "上传", safe_filename(entry.client_name)]) File.mkdir_p!(路径.dirname(dest)) File.cp!（路径，目标） {：好的，~s(/uploads/#{Path.basename(dest)})} 结束） # 使用 uploaded_files 路径保存到数据库 {：noreply，分配（套接字，：uploaded_files，uploaded_files）} 结束 defp safe_filename(original_name) 做 # 生成唯一的名称以防止冲突和攻击 ext = Path.extname(原始名称) “#{Ecto.UUID.generate()}#{ext}” 结束 ### 模板 <.simple_form for={@form} phx-change="validate" phx-submit="save"> <.input field={@form[:title]} label="标题"/>

<.label>上传照片 <.live_file_input upload={@uploads.photos} />

<%= 对于错误 <- upload_errors(@uploads.photos) 执行 %>

<%= error_to_string(err) %>

<％结束％> <%= 条目 <- @uploads.photos.entries 执行 %>

<.live_img_preview条目={entry} /> <进度值={entry.progress} max="100"><%=entry.progress %>% <%= 对于错误 <- upload_errors(@uploads.photos, entry) 执行 %>

<%= error_to_string(err) %>

<％结束％>

<％结束％> <:动作> <.button phx-disable-with="上传...">上传 ## 错误处理始终实现 `error_to_string/1`： defp error_to_string(:too_large), do: “文件太大（最大 10MB）” defp error_to_string(:not_accepted), do: "文件类型不被接受" defp error_to_string(:too_many_files), do: “选择了太多文件” defp error_to_string(:external_client_failure), do: "上传失败" ## 静态文件服务配置 **关键：** 上传文件后，必须通过 static_paths 提供它们。 ### 第 1 步：定义 static_paths/0 # lib/my_app_web.ex def static_paths 做〜w（资产字体图像上传favicon.ico robots.txt）结束 **规则：** 您提供文件的任何目录都必须在此处列出。 ### 步骤 2：验证 Plug.Static 配置 # lib/my_app_web/endpoint.ex 插头 Plug.Static, 在：“/”，来自：：我的应用程序， gzip：假，仅：MyAppWeb.static_paths() ### 文件结构静态文件必须位于“priv/static/”中：我的应用程序/ ├── 私人/ │ └── 静态/ │ ├── asset/ # CSS, JS (来自 esbuild) │ ├── uploads/ # 用户上传 │ │ ├── 图片1.jpg │ │ └── doc.pdf │ └── favicon.ico ## 提供上传的文件 ### 来自模板

<.link href="/uploads/document.pdf" download>下载 ### 来自控制器 def download(conn, %{"filename" => filename}) 执行 # 清理文件名以防止路径遍历 safe_name = Path.basename(文件名) path = Path.join(["priv", "static", "上传", safe_name]) 如果 File.exists?(path) 和 String.starts_with?(path, "priv/static/uploads") 执行 send_download(conn, {:文件, 路径}, 文件名: safe_name) 否则康涅狄格州 |> put_status(:not_found) |> text("未找到文件") 结束结束 ## 图像预览对于图像上传，显示预览： <%= 条目 <- @uploads.photos.entries 执行 %>

<.live_img_preview条目={entry}宽度={200}/> <按钮类型=“按钮”phx-click=“取消上传”phx-value-ref={entry.ref}> 取消

<％结束％> @impl true def handle_event("取消上传", %{"ref" => ref}, socket) do {：noreply，cancel_upload（套接字，：照片，参考）} 结束 ## 多个上传槽您可以有多个上传配置：插座 |> 允许上传(:照片, 接受: ~w(.jpg .jpeg .png), max_entries: 5) |> 允许上传（：文档，接受：~w（.pdf .docx），最大条目数：3） ## 外部存储（S3等）对于外部存储，请使用 `:external` 选项：允许上传（：照片，接受：~w(.jpg .jpeg .png), 最大条目数：5，外部：&presign_upload/2 ） defp presign_upload(entry, socket) 做 # 为 S3 生成预签名 URL {:ok, %{上传者: "S3", key: key, url: url}, 套接字} 结束 ## 故障排除 ### 文件返回 404 **问题：** 访问 `/uploads/file.jpg` 返回 404 **修复：** 1.检查static_paths是否包含“uploads” 2. 验证文件是否存在于 `priv/static/uploads/` 中 3. **更改 static_paths 后重新启动服务器** 4.检查文件权限（应该可读） # 调试助手 def check_static_file(路径) 做 full_path = Path.join(["priv", "static", 路径]) 条件做不是 File.exists?(full_path) -> “文件不存在：#{full_path}” 不是文件可读？（完整路径）-> “文件存在但不可读：#{full_path}” 正确-> “文件确定：#{full_path}” 结束结束 ### 文件在开发中有效，但在生产中无效 **问题：** 文件在本地正常运行但在生产中失败 **修复：** 1. **部署前运行`mix phx.digest`：** MIX_ENV=产品组合 phx.digest 2. **检查生产端点配置：** # 配置/运行时.exs 配置：my_app，MyAppWeb.Endpoint， cache_static_manifest：“priv/static/cache_manifest.json” 3. **确保文件已部署：** # 检查您的部署是否包含 priv/static/ ## 安全最佳实践 ### 1\.清理文件路径 **永远不要**直接在文件路径中使用用户输入： # ❌ 危险 - 路径遍历攻击 defserve_file(conn, %{"path" => user_path}) 做 send_file(conn, 200, "priv/static/#{user_path}") 结束 # ✅ SAFE - 验证和约束 defserve_file(conn, %{"filename" => filename}) 做 safe_name = Path.basename(filename) # 去掉目录遍历 path = Path.join(["priv", "static", "上传", safe_name]) 如果 File.exists?(path) 和 String.starts_with?(path, "priv/static/uploads") 执行发送文件（连接，200，路径）否则 send_resp（conn，404，“未找到”）结束结束 ### 2\.验证文件类型不要信任客户端 MIME 类型： def validate_file_type(路径) 做 # 使用像 `file_type` 这样的库来验证实际内容 case FileType.from_path(path) 做 {:ok, %{mime_type: "image/" <> _}} -> :ok _ -> {:错误, :invalid_type} 结束结束 ### 3\.生成唯一的文件名防止碰撞和路径遍历： defp safe_filename(original_name) 做 ext = Path.extname(原始名称) “#{Ecto.UUID.generate()}#{ext}” 结束 ### 4\.限制文件大小设置合理的限制：允许上传（：照片，接受：~w(.jpg .jpeg .png), 最大条目数：5，最大文件大小: 10_000_000 # 10MB ） ### 5\.内容类型标头设置适当的内容类型以防止 XSS： defserve_image(conn, %{"id" => id}) 做图像 = get_image!(id) 康涅狄格州 |> put_resp_header("内容类型", image.content_type) |> put_resp_header("x-content-type-options", "nosniff") |> send_file(200, 图像.路径) 结束 ## 测试上传测试“上传图片成功”，%{conn: conn} do {:ok, lv, _html} = live(conn, "/画廊") 图像= file_input(lv, "#upload-form", :照片, [ %{ 名称：“测试.png”，内容：File.read!("test/fixtures/test.png"), 类型：“图像/png” } ]）断言 render_upload(image, "test.png") =~ "100%" LV |> 表单("#upload-form") |> render_submit() 断言 has_element?(lv, "img[alt='test.png']") 结束 ## 常见陷阱 ### ❌ 使用 auto_upload 和表单提交 # 不要这样做 allowed_upload(:照片, auto_upload: true, ...) def handle_event("保存", _params, socket) 做 Consumer_uploaded_entries(socket, :photos, ...) # 行不通！结束 ### ✅ 使用手动上传代替 # 这样做允许上传（：照片，...） def handle_event("保存", _params, socket) 做 Consumer_uploaded_entries(socket, :photos, ...) # 有效！结束 ### ❌ 不处理上传错误 <.live_file_input upload={@uploads.photos} /> ### ✅ 始终显示错误 <.live_file_input upload={@uploads.photos} /> <%= 对于错误 <- upload_errors(@uploads.photos) 执行 %>

<%= error_to_string(err) %>

<％结束％> ### ❌ 忘记静态路径 # 文件保存到 priv/static/uploads/ # 但“上传”不在 static_paths 中 def static_paths, do: ~w(assets favicon.ico) # 缺少上传！ ### ✅ 包含上传目录 def static_paths, do: ~w(资产上传 favicon.ico) ## 快速参考 # 1. 将目录添加到 static_paths def static_paths, do: ~w(资产上传 favicon.ico) # 2.创建目录结构私人/静态/上传/ # 3. mount中配置上传允许上传（：照片，接受：~w（.jpg .png），最大条目数：5） # 4. 在handle_event中消费 Consumer_uploaded_entries(socket, :photos, fn %{path: path}, 条目 -> dest = Path.join(["priv", "static", "上传", safe_filename(entry.client_name)]) File.mkdir_p!(路径.dirname(dest)) File.cp!（路径，目标） {:ok, "/uploads/#{Path.basename(dest)}"} 结束） # 5. 模板中的引用

# 6. 重新启动服务器以应用更改混合 phx.server ## 测试在编写文件上传功能的测试时，请在编写任何“_test.exs”文件之前调用“elixir-phoenix-guide:testing-essentials”。

凤凰上传

包含技能