写苍穹外卖这个项目到第十一天基本把管理端的功能串起来了。今天没设计新表也没写特别复杂的业务但搞定的是整个系统里存在感很低、却是刚需的一环——本地上传图片。说白了就是管理员在后台新增菜品、套餐的时候可以从本地选一张图片传上去页面立刻能显示出来。这功能看着不起眼真正动手做一遍涉及的点和踩坑的地方比想象中多值得单独记上一篇。这篇日记我打算按照从方案选型、后端实现、前端联调到问题排查的顺序来写顺便把本地方案和以后换成云端存储的思路也捋一遍给还卡在“图片传上去了但页面不显示”的朋友一个完整的参考。1. 今天要做什么图片上传是怎么被一步步逼出来的1.1 项目走到这一步为什么突然要做图片上传苍穹外卖这个项目到第十天的时候管理端的基础业务已经跑得差不多了员工登录、JWT鉴权、分类管理、菜品管理、套餐管理新增和修改的接口都通了数据库表也正经维护起来了。但有一个问题一直悬着——菜品没有图片。不是不想展示是压根没有传图的能力。餐饮外卖类应用菜品图几乎是灵魂。用户在客户端点餐时第一眼看到的就是图片没图的菜品很难带来点击。对于管理端来说如果没有图片上传新增菜品时图片字段只能存一个写死的URL或者空字符串那就意味着“数据闭环”并没有真正跑通。第十一天的核心任务就是把这条链路补上。大概流程是这样管理员打开新增菜品页面选择本地的 jpg 或 png 图片前端先把文件发到后端后端把文件存到服务器磁盘的某个目录再把访问路径返回给前端前端拿到路径后渲染成 img 标签。听上去就这么几步但它牵扯出文件类型校验、静态资源映射、跨域、token鉴权、上传大小限制、URL拼接等一系列问题。1.2 这个功能最适合谁来参考如果你正在跟苍穹外卖的教学视频或文档敲代码那这篇日记其实就是在你最容易卡住的地方做了详细展开。尤其是“本地上传图片”这个点很多人做着做着就发现接口写好了、文件也传上去了但图片就是显示不出来。问题往往不在上传本身而在“上传后如何让浏览器能访问到”这个环节。除了跟项目的人只要是后端开发才刚起步、对Spring Boot的文件上传和静态资源映射还不太熟的同学这篇也可以当个案例看。我会把关键代码完整贴出来也会把每个配置背后的原因说清楚方便你迁移到自己负责的模块里。毕竟文件上传不是外卖项目独占的需求后台管理系统里换个头像、传个附件、导入个Excel本质都是同一套东西。1.3 影响范围比想象中要广图片上传看起来是给“菜品管理”服务的一个小功能但一旦后端把“通用文件上传”的接口做好了它就变成了一条基础设施。以后店铺logo、用户头像、商品分类图标、营销活动图片全都可以复用同一个入口。所以在设计的时候我就没打算把存储逻辑写死在某个业务Controller里而是单独抽出来让所有模块都走同一个上传接口。这就像家里装了一个公共水龙头每个房间需要用水的时候直接接管子就行不用每家再各自挖一口井。接口统一之后后面想加“图片大小限制”“图片压缩”“格式校验”都只用改一处。这也是我今天特别想强调的一个习惯写功能的时候多想一层“以后谁会复用”代码质量会完全不一样。2. 本地图片上传方案选型开发阶段为什么先不直接上OSS2.1 三种方案摆在面前我为什么选了本地存储项目开发到第十一天最自然的疑问是图片存哪里网上很多教程一上来就让你配阿里云OSS、腾讯云COS说将来生产环境一定用得上。这话没错但放在学习阶段和本地开发阶段并不一定最优。我当时面前摆了三个方案本地磁盘存储文件保存到项目指定目录后端配置静态资源映射浏览器通过URL直接访问。零成本、零依赖、debug方便。云存储OSS/COS文件传到第三方对象存储服务返回公网URL。生产环境很稳但需要开通服务、配置密钥本地调试时还受网络环境影响。数据库存储存Base64或BLOB把图片转成Base64直接存字段里。小型项目能跑但数据库体积膨胀快读写效率低下不建议作为通用方案。我最终选了本地磁盘存储。原因很直接苍穹外卖这个项目在现阶段主要跑在本地开发环境没有公网访问需求也没有大并发文件请求用本地路径最简单有效。开发阶段如果过度设计把时间都耗在开通云服务、配权限上反而拖慢业务进度。存储方案本身是可替换的先把业务跑通日后上线前再换OSS也来得及。2.2 本地存储和云存储的对比心里得有杆秤选本地方案不代表不关注云存储的优缺点。只有把两者边界想清楚以后切换时才不会手忙脚乱。我个人整理过一张对比表做技术决策时可以直接拿来参考对比维度本地磁盘存储云存储OSS/COS成本基本为零用服务器磁盘即可按存储容量和流量计费有免费额度但长期有成本访问速度同机房内访问快直接走静态映射依赖公网但通常有CDN加速跨地域表现更好可用性单机磁盘有损坏风险需要自己做备份服务商保障多副本冗余可用性很高扩展性单机磁盘有限扩容需要挂盘或迁移弹性扩容无需关心物理容量开发难度本地配置简单适合调试需要引入SDK、配置密钥多一步依赖开发阶段选本地是因为“快”最重要生产阶段上云是因为“稳”和“可靠”更重要。这不是哪个方案更好而是阶段不同、优先级不同。做技术选型的时候最忌讳的就是抱着“某个技术潮流”不放完全不顾当前项目的实际约束。2.3 存储路径的设计别把文件全扔进一个目录里确定了本地存储下一个问题是文件存到磁盘上的哪个位置。我见过不少同学为了省事直接把上传的文件写到项目的 src/main/resources/static 下面结果一来项目重新编译打包时文件容易被清掉二来静态资源目录和源代码目录混在一起维护起来很难受。更合理的做法是设置一个独立的存储根目录比如在项目部署目录之外建一个 upload 文件夹再通过配置项告诉Spring Boot这个目录在哪。目录结构上我也建议按日期分子目录比如 upload/2025/04/10/xxx.jpg。好处有三个第一单目录下文件数量可控不会几千张图堆在一起文件系统访问性能更好第二按时间组织比较直观出了问题按日期排查很快第三后续做定期清理策略的时候可以直接按日期目录批量删除方便得多。这个设计思路很朴素但属于那种“不写下来你可能不会注意踩过一次坑就会一直记住”的细节。3. 后端实操通用文件上传接口如何一步步落地3.1 配置文件先打好底子开发环境下的本地存储用Spring Boot做文件上传本身就很容易。我先在 application.yml 里加了文件上传的配置把大小限制和编码方式钉死spring: servlet: multipart: max-file-size: 10MB max-request-size: 10MBmax-file-size 是单个文件的大小上限max-request-size 是一次请求体的大小上限。做图片上传场景默认的1MB往往不够用菜品照片随手一拍就好几兆。但设得太大也有风险服务器内存会被大文件拖垮。我在地图项目里习惯把上限控制在10MB既满足业务场景又不会给服务器带来太大压力。然后我在配置类里加一个自定义的存储路径配置项比如在 application.yml 里加 upload.path指向本机的图片存储目录sky: upload: path: D:/upload/为什么不用硬编码路径因为Windows开发环境和Linux服务器环境路径规则不一样写死在代码里以后部署到服务器必然要改代码。把路径放到配置里部署时只改配置就行代码一行不用动。这也是我反复提醒自己的“配置与代码分离”原则哪怕项目很小这个习惯也得保持。3.2 核心Controller通用上传接口的设计思路接口路径我定义成 /api/common/upload语义是“通用文件上传”。这样设计的原因是菜品、套餐、用户头像这些业务模块将来都能调它没必要在业务Controller里各写一套上传逻辑。返回结果统一用 Result 包装里面带上图片的可访问URL前端拿到直接回显。下面是精简后的核心代码RestController RequestMapping(/api/common) Slf4j public class CommonController { Autowired private FileStorageService fileStorageService; PostMapping(/upload) public ResultString upload(MultipartFile file) { if (file null || file.isEmpty()) { return Result.error(上传文件不能为空); } String url fileStorageService.store(file); return Result.success(url); } }这里我没有把存储逻辑写在Controller里而是抽了一个 FileStorageService。为什么这样拆因为Controller的职责是接收请求、参数校验、返回结果至于文件是存到本地磁盘还是上传到OSS完全是另一层的事。这样抽出来后面想把本地存储换成OSS时只需要实现一个新的 FileStorageService 实现类Controller不用动。这个设计原则叫“面向接口编程”说开了就是“上层别关心底层怎么干活”。3.3 文件存储与拦截校验细节FileStorageService 的实现类里做的事情主要有四步校验文件类型、生成新文件名、保存文件到指定目录、拼接访问URL。每一步都有文章可做。文件类型校验上不能只信前端后端一定要做二次校验。前端判断文件类型只是提升用户体验真正要防的是有人绕过页面直接调接口传个可执行文件上去。我在后端用了两层校验先判断扩展名白名单再读取文件头魔数来确认真实格式。魔数校验是关键因为扩展名可以改但文件头的二进制标识改不了JPEG开头是 FFD8FFPNG开头是 89504E47GIF开头是 47494638后端把这些读出来比对才是最稳的。文件名处理上我直接用 UUID 重命名。原来的文件名不能直接作为存储名原因有两个一是中文文件名容易产生编码问题在Linux服务器上尤其明显二是用户上传的 tmp.png 和另一个用户上传的 tmp.png 会互相覆盖。UUID生成的名字全球唯一既避免冲突又隐藏了原始文件路径信息算是一举三得。但也不能完全丢掉后缀不然浏览器没办法根据扩展名解析图片类型所以新文件名是 UUID.原后缀 的格式。拼接访问URL时我存的是一个相对路径 /upload/文件名而不是绝对路径。这样做的原因很直接不同环境IP和端口不同绝对路径写死以后换环境就废了。前端拿到相对路径后根据自己的部署地址做拼接就行灵活得多。3.4 静态资源映射文件存上了还得让浏览器能访问文件保存到D盘之后浏览器并不能直接访问它。要让用户通过URL看到图片后端必须把那块磁盘目录映射成一个HTTP可访问的虚拟路径。我按Spring Boot的WebMvcConfigurer配置方式写一个配置类Configuration public class WebMvcConfig implements WebMvcConfigurer { Value(${sky.upload.path}) private String uploadPath; Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/upload/**) .addResourceLocations(file: uploadPath); } }这段代码的意思是所有访问 /upload/ 开头的URL都去 uploadPath 这个本地磁盘目录下找文件。比如浏览器访问 http://localhost:8080/upload/abc.jpg实际上是从 D:/upload/abc.jpg 读文件返回。这里有个细节值得注意addResourceLocations 的参数必须以 file: 开头并且路径结尾要带斜杠。少了 file: 前缀Spring不认识这是本地文件系统路径少了结尾斜杠路径拼接会出问题。Windows和Linux都适用只要配置路径写正确就行。另外如果项目里用了网关或拦截器还要确认 /upload/** 路径是否被拦截器拦下来了。苍穹外卖的JWT拦截器一般会拦截部分路径如果拦截规则把 /upload/** 也拦了静态资源一样访问不了。这个我在后面排查部分会展开讲。4. 前端对接与图片回显一张图完整显示出来才算结束4.1 ElementUI的el-upload组件怎么接后端苍穹外卖的前端管理后台用的是Vue ElementUI。图片上传组件首选 el-upload因为它自带选择文件、进度条、上传成功回调不需要自己写一堆Ajax代码。前端需要配置的关键属性有这么几个action 是后端上传接口的完整URLheaders 需要带上登录后存的token因为后端接口在JWT拦截器保护下不带token会返回401show-file-list 可以设成false因为我们只要一张图on-success 是上传成功后的回调用来接收后端返回的图片URL并回显before-upload 用来做前端预校验比如限制文件类型和大小让用户早点知道问题省得等到上传完才报错。核心代码大致是el-upload v-loadingloading classavatar-uploader actionhttp://localhost:8080/api/common/upload :headers{ Authorization: token } :show-file-listfalse :on-successhandleSuccess :before-uploadbeforeUpload img v-ifimageUrl :srcimageUrl stylewidth: 120px; height: 120px; alt菜品图 / /el-upload需要提醒的是action 里的地址是开发环境的直连地址。如果项目引入了网关或Nginx做反向代理这里应该填代理后的地址而不能直接写 localhost:8080。很多同学本地能跑通一联调就报404往往就是前端请求地址和后端真实地址没对齐。4.2 回显的URL拼接问题这是显示不出来的头号原因前端拿到后端返回的URL后回显时要特别注意拼接路径。后端我设计返回的是相对路径 /upload/xxx.jpg前端如果直接用这个值塞给 img 标签的 src浏览器会把它当成当前域名下的地址去请求。打个比方前端页面跑在 http://localhost:8081那么 src/upload/xxx.jpg 就会被解析成 http://localhost:8081/upload/xxx.jpg但上传的文件实际是由后端 8080 端口提供的端口对不上图片自然404。解决方式有两种。第一种是前端根据环境拼接前缀判断当前环境变量然后加上对应后端地址。第二种是后端直接返回完整URL比如 http://localhost:8080/upload/xxx.jpg。两种方案我以前都用过如果项目只是本地开发后端返回完整URL很省事但一旦部署到正式环境域名、HTTPS、端口一堆变量后端写死完整URL反而更难维护。所以我还是推荐相对路径 前端拼接的方式这也是很多企业项目的实践做法。看上去多了一步操作但换来的是环境切换时的灵活性。4.3 上传成功后的交互细节上传成功后我习惯在回调里做三件事把后端的imageUrl填到表单数据里把 loading 状态关掉如果有图片预览字段更新一下v-model绑定的值。表单提交时图片URL作为普通字段一起提交给后端存库这样菜品管理接口本身一点不用改新增数据时把图片URL带进来就行。还要注意错误处理。on-success 不能只看HTTP响应码因为后端业务层可能返回“文件类型不支持”这类错误HTTP仍然是200。正确的做法是在回调里判断后端返回的code只有code为成功时才走正常逻辑如果code是错误码就弹个提示把后端错误信息展示给用户同时清掉loading状态。这个细节漏掉的话会出现“前端显示上传成功但后端根本没存文件”的诡异情况。5. 这些坑我都替你踩过上传功能排查实录5.1 上传成功但浏览器访问图片404这是第十一天开发中遇到最多的一个问题当时我还排查了好一会儿。现象是接口返回了 /upload/abc.jpg文件也确实出现在D盘目录里但浏览器访问URL返回404。排查路径是这样先确认静态资源映射是否生效直接在后端日志里看访问 /upload/abc.jpg 有没有对应请求记录然后确认配置类有没有被Spring扫描到我遇到过把配置文件放在了子包外面导致不生效的情况最后确认路径拼接正确uploadPath 结尾有没有带斜杠addResourceLocations 有没有加 file: 前缀。前两步都正常问题基本就锁定在配置细节上。当时我的问题就出在路径末尾少了斜杠整个地址被拼成了 file:D:/uploadabc.jpg自然找不到文件。还有一种可能性是拦截器挡掉了 /upload/** 请求。苍穹外卖里JWT拦截器通常只拦截 /api/** 等业务路径但如果拦截规则写得太宽把静态路径也包含进去了就会导致图片请求被拦截。解决办法是把 /upload/** 加到拦截器的放行列表里。5.2 大图片上传报错提示文件超出大小限制项目刚配置好上传功能后我试传一张6MB的菜品照片结果前端直接报错后端日志提示 max file size 超出异常。一看配置spring.servlet.multipart.max-file-size 还是默认的1MB自然传不上去。配置改成10MB后原以为就结束了结果在联调环境又遇到同样的问题后来才发现Nginx层还有 client_max_body_size 限制默认1MB文件在到达后端前就被Nginx挡回来了。所以排查上传大小问题时要同时检查两层应用层的multipart配置和网关层的请求体大小限制。这是个很典型的多层排查场景漏掉任何一层都会被坑。5.3 浏览器一直显示旧的菜品图片这个坑特别隐蔽不是功能问题是缓存问题。图片上传成功后我反复修改并重新上传同一张图片但页面显示的始终是旧图。因为图片URL没变浏览器认为资源没更新就直接用了本地缓存。解决方式有两个一是上传成功后给图片URL加一个时间戳参数比如 /upload/abc.jpg?v20250410让浏览器把它当作新资源去请求二是在前端配置Nginx时对图片类型的缓存策略不要设太久。开发阶段用第一种方式最省事改一行代码就行。这个细节不实际遇到一次很难想起来。5.4 排查速查表下次照着查就行现象可能原因处理方式上传成功但图片404静态资源映射配置错误检查 file: 前缀、结尾斜杠、配置类是否被扫描图片请求被拦截拦截器范围过大在拦截器中放行 /upload/**大文件上传失败multipart 或 Nginx 限制调整 Spring max-file-size 和 Nginx client_max_body_size图片一直显示旧图浏览器缓存图片URL加时间戳参数上传接口返回401请求头未携带token前端 headers 里带上登录后的 Authorization中文文件名乱码原始文件名直接存储用UUID重命名文件这张表我打算直接保留在项目笔记里后面再遇到上传相关问题先按这张表排查一遍大多数情况都能定位到原因。6. 从本地到OSS给以后留一条平滑升级的路6.1 本地方案的上限在哪里本地存储不是万能方案得清楚它的瓶颈在哪。最明显的上限是单机磁盘容量。开发阶段的照片少几百张没问题但生产环境下图片量会快速膨胀磁盘迟早会爆。第二个限制是可用性。单机部署时本地磁盘一旦故障所有图片都会丢这对线上业务来说是致命的。第三个限制是访问带宽。图片请求全压在一台Web服务器上网络流量一大服务器响应就会变慢。所以我的判断是本地存储适合开发、测试、单机小规模部署一旦要正式上线、对外提供服务最好换成对象存储服务。这不代表今天的工作白做了反而因为接口层抽得干净切换成本非常低。6.2 用接口隔离存储实现切换时只需动一处为了让后期“改存储方案”变得容易我今天写代码时特意把存储逻辑封装成了接口Controller依赖的是 FileStorageService而不是某个本地存储类。这样做的好处是将来新增一个 OSSStorageService 实现类在配置里切换一下注入的实现业务代码完全不用变。接口大致是这样public interface FileStorageService { String store(MultipartFile file); }本地实现的 store 方法负责存磁盘、返回 /upload/xxx.jpg以后阿里云OSS实现的 store 方法负责调用OSS SDK、返回公网URL。Controller层面看到的只有 store 方法根本不关心文件到底存哪了。这个模式也让单元测试更容易测试时注入一个Mock实现就行不需要真的传文件到磁盘。6.3 如果想直接上OSS核心流程是什么样的如果你暂时不想用本地方案想直接照着OSS的接入方式写核心流程也差不多先引入对象存储SDK依赖在配置文件里配置AccessKey、Bucket名称、Endpoint然后写一个工具类封装文件上传操作调用SDK的putObject方法最后在FileStorageService的OSS实现类里调用工具类返回文件的公网访问地址。有一点要特别注意AccessKey一旦泄露别人就能操作你的存储空间正规项目中AccessKey一定不要写死在代码里要通过环境变量或者配置中心管理。这一点比我前面写的所有编码细节都重要不管项目大小密钥管理这根弦要领牢。现阶段我仍然用本地方案但通过预留接口和配置项已经把“将来要换OSS”的路铺好了。技术上最怕的不是现在选错了方案而是把代码写死让以后连换的机会都没有。写到这里第十一天的开发算是收尾了。我个人在做完本地上传图片这个功能后最大的体会是一个看似简单的上传功能要真正做得“完整”从后端校验、文件命名、存储路径、静态映射到前端回显、缓存处理、网关限制每个环节都得有意识地去处理而不是只把文件保存下来就完事。最后再分享一个小技巧开发阶段如果你频繁上传同一张图片测试记得在URL后面加个时间戳参数否则浏览器缓存会让你误以为功能坏了。这个细节我今晚就踩过写出来帮你避开。