简介：这份资源面向需要实现微信小程序文件上传功能的开发者，尤其适合正在搭建前后端分离项目、希望对比多种上传方案的 Java 与小程序学习者。包内代码分为微信小程序前端与 Java 后台两部分，重点演示两种上传路径：一是上传至 Java 本地服务器，对应 IndexController；二是上传至独立文件服务器，由 NginxController 与 UploadController 分别实现，前者调用 service 与实体类完成分层处理，后者则直接编写上传逻辑，便于读者对比两种写法的差异与适用场景。资源共 23 个文件，以 9 个 java 源码、4 个 json 配置、3 个 js 脚本及 wxss、wxml 等小程序页面文件为主，另含 yml、xml 等工程配置，压缩包约 15KB，结构紧凑。目前已有 2194 人学习下载，可作为快速理解小程序上传链路、后台接口分层与文件服务器对接思路的参考示例。
1. 从一次“上传失败”说起：这个压缩包到底解决了什么
你有没有遇到过这种情况：微信小程序里选好文件，点了上传，进度条卡在 99%，然后弹出一个红色的“上传失败”。排查半天发现不是网络问题，也不是文件太大，而是后端接口根本没接住multipart/form-data的流。这个名为“微信小程序上传文件到文件服务器.rar”的压缩包，解决的就是这类问题——它把小程序端选文件、上传、后端 Java 接收、落盘到独立文件服务器的完整链路打包好了。适合正在做小程序文件上传功能、又不想从零踩坑的后端和全栈开发者。技术栈是 Java 后端加微信小程序前端，核心是文件流的中转与存储分离。拿到源码后，你可以直接跑通上传流程，再按自己的存储策略改造成熟的文件服务。
2. 项目结构拆解：从压缩包到可运行工程
2.1 目录布局与模块职责
解压后你会看到一个典型的双端工程结构。根目录下通常分两个文件夹：一个放微信小程序端代码，一个放 Java 后端服务。小程序端包含pages、utils、app.json等标准文件，后端则是一个 Maven 或 Gradle 项目，里面有controller、service、config等包。这种分法很常见，好处是前后端可以独立部署，文件服务器也能单独扩容。
我一般会先看后端的pom.xml或build.gradle，确认依赖了哪些库。这个项目里大概率有spring-boot-starter-web用来提供 HTTP 接口，可能还有commons-fileupload或直接使用 Spring 的MultipartFile。小程序端则依赖微信基础库，不需要额外 npm 包，直接用wx.uploadFile就行。
提示：如果你拿到的压缩包里没有
pom.xml，检查一下是不是把源码和编译产物混在一起了，只保留src目录重新构建即可。
2.2 后端接收接口的代码实现
后端最核心的是一个接收上传的 Controller。下面这段代码是我根据项目场景补全的典型写法，你可以对照源码里的实际类名调整。
@RestController @RequestMapping("/api/file") public class FileUploadController { @Autowired private FileStorageService fileStorageService; @PostMapping("/upload") public ResponseEntity<String> uploadFile(@RequestParam("file") MultipartFile file, @RequestParam(value = "bizType", defaultValue = "default") String bizType) { // 校验文件是否为空 if (file.isEmpty()) { return ResponseEntity.badRequest().body("上传文件不能为空"); } // 生成存储路径，按业务类型分目录 String originalFilename = file.getOriginalFilename(); String storedPath = fileStorageService.save(file, bizType); // 返回可访问的文件标识，而不是完整路径 return ResponseEntity.ok(storedPath); } }这段代码的逻辑很直白：接收MultipartFile和业务类型参数，交给FileStorageService去落盘。参数bizType用来区分不同业务的上传，比如头像、附件、导入数据，方便后续按目录管理。返回的storedPath通常是一个相对路径或文件 ID，前端拿到后再拼成完整 URL 去访问。
注意@RequestParam("file")里的名字必须和小程序端wx.uploadFile的name参数一致，否则后端收不到文件流，直接报 400。这是最常见的翻车点之一。
2.3 文件存储服务的落盘策略
FileStorageService决定了文件最终写到哪里。这个项目既然叫“上传到文件服务器”，说明存储位置和 Web 应用是分离的。常见做法有两种：一种是挂载 NFS 或 SMB 共享目录，另一种是通过 FTP/SFTP 推送到独立文件服务器。下面是一个本地目录存储的简化实现，你可以根据实际环境改成远程推送。
@Service public class FileStorageService { @Value("${file.storage.root-path}") private String rootPath; public String save(MultipartFile file, String bizType) { // 按业务类型和日期分目录，避免单目录文件过多 String dateDir = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyyMMdd")); Path dir = Paths.get(rootPath, bizType, dateDir); try { Files.createDirectories(dir); // 用 UUID 重命名，防止文件名冲突和路径穿越 String ext = StringUtils.getFilenameExtension(file.getOriginalFilename()); String newFileName = UUID.randomUUID().toString().replace("-", "") + "." + ext; Path target = dir.resolve(newFileName); file.transferTo(target.toFile()); // 返回相对路径，由前端或网关拼成完整 URL return bizType + "/" + dateDir + "/" + newFileName; } catch (IOException e) { throw new RuntimeException("文件存储失败", e); } } }这里有几个关键点：rootPath从配置文件读取，方便不同环境切换；按bizType/日期分目录，避免一个目录下文件数量爆炸；用 UUID 重命名，既防冲突也防用户上传恶意文件名。返回相对路径而不是绝对路径，是为了不暴露服务器目录结构。
如果你要改成推送到独立文件服务器，把file.transferTo换成 FTP 客户端的storeFile即可，其他逻辑不变。
2.4 小程序端上传代码与参数说明
小程序端调用wx.uploadFile发起上传。下面是一个带进度提示和错误处理的完整示例。
// pages/upload/upload.js Page({ data: { progress: 0, uploadedUrl: '' }, chooseAndUpload: function () { const that = this; wx.chooseMessageFile({ count: 1, type: 'file', success(res) { const file = res.tempFiles[0]; // 限制大小，比如 20MB if (file.size > 20 * 1024 * 1024) { wx.showToast({ title: '文件不能超过20MB', icon: 'none' }); return; } const uploadTask = wx.uploadFile({ url: 'https://your-domain.com/api/file/upload', filePath: file.path, name: 'file', // 必须与后端 @RequestParam 名称一致 formData: { bizType: 'attachment' }, success(resp) { // 后端返回的是字符串，需要手动解析 const data = JSON.parse(resp.data); that.setData({ uploadedUrl: data }); wx.showToast({ title: '上传成功', icon: 'success' }); }, fail(err) { console.error('上传失败', err); wx.showToast({ title: '上传失败，请重试', icon: 'none' }); } }); // 监听进度 uploadTask.onProgressUpdate((res) => { that.setData({ progress: res.progress }); }); } }); } });wx.chooseMessageFile是从聊天记录里选文件，也可以换成wx.chooseMedia选图片视频。name参数必须和后端@RequestParam("file")完全一致，大小写敏感。formData里可以带额外的业务参数，后端用@RequestParam接收。注意success回调里的resp.data是字符串，不是对象，直接JSON.parse才能拿到后端返回的路径。
进度条通过uploadTask.onProgressUpdate实现，适合大文件上传时给用户反馈。如果上传过程中用户退出页面，记得在onUnload里调用uploadTask.abort()，否则会继续消耗流量。
3. 跑起来：环境准备与联调步骤
3.1 后端启动与配置修改
拿到源码后，第一步是改配置文件。找到application.yml或application.properties，把数据库连接、文件存储根路径、服务端口改成你本地的。如果项目用了 MySQL，先建好库，执行schema.sql或手动建表。文件存储路径要确保 Java 进程有读写权限，Windows 下别用C:\Windows这种敏感目录，Linux 下别用/root。
server: port: 8080 file: storage: root-path: /data/upload/files # 改成你自己的目录 spring: servlet: multipart: max-file-size: 50MB # 单文件大小限制 max-request-size: 100MB # 整个请求大小限制max-file-size和max-request-size必须根据业务调整，默认值只有 1MB 和 10MB，上传大文件会直接抛MaxUploadSizeExceededException。改完后用mvn spring-boot:run或java -jar启动，看到 “Started Application” 就算成功。
3.2 小程序端配置与真机调试
小程序端需要改两个地方：一是project.config.json里的appid，换成你自己的小程序 AppID；二是上传接口的url，改成后端服务的地址。本地开发时，微信开发者工具需要勾选“不校验合法域名”，否则wx.uploadFile会报域名不合法。
真机调试时，手机和电脑要在同一个局域网，后端地址用电脑的局域网 IP，比如http://192.168.1.100:8080/api/file/upload。如果手机访问不了，检查防火墙是否放行了 8080 端口。上传成功后，去后端配置的root-path目录下看有没有生成文件，有就说明链路通了。
3.3 用 Postman 先验证后端接口
在联调小程序之前，我习惯先用 Postman 测后端接口，排除小程序端的干扰。新建一个 POST 请求，URL 填http://localhost:8080/api/file/upload，Body 选form-data，key 写file，类型选File，选一个本地文件发送。如果返回了路径字符串，说明后端没问题。如果报 400，检查@RequestParam名称是否匹配；如果报 500，看后端日志里的异常堆栈，多半是存储路径没权限或磁盘满了。
这一步能省掉很多“到底是前端还是后端问题”的扯皮。确认后端 OK 后，再去调小程序，问题范围就缩小到前端配置了。
4. 避坑指南：上传功能最常见的五个翻车点
4.1 现象：小程序上传报 “fail url not in domain list”
原因：微信小程序正式环境要求所有请求域名在后台白名单里，本地开发时如果没勾选“不校验合法域名”，也会报这个错。解决：开发阶段在开发者工具右上角“详情”里勾选不校验；上线前把后端域名加到小程序后台的request和uploadFile合法域名列表里，注意必须是 HTTPS。
4.2 现象：后端收到文件但大小为 0
原因：小程序端wx.uploadFile的name参数和后端@RequestParam名称不一致，或者formData里重复传了同名参数。解决：两边名称严格对齐，formData里不要放和文件同名的 key。另外检查Content-Type是不是multipart/form-data，这个由wx.uploadFile自动设置，不要手动改。
4.3 现象：上传大文件时连接超时
原因：Nginx 或 Spring Boot 的请求体大小限制、超时时间没调。解决：Nginx 里加client_max_body_size 100m;和proxy_read_timeout 300s;；Spring Boot 里调大max-file-size和max-request-size。如果用了网关，网关的超时也要同步放大。
4.4 现象：文件名乱码或路径穿越
原因：直接用了file.getOriginalFilename()拼路径，中文文件名在不同操作系统下编码不一致，恶意文件名可能包含../。解决：不要用原始文件名存盘，用 UUID 重命名，只保留扩展名。扩展名也要做白名单校验，比如只允许jpg、png、pdf、docx，防止上传可执行文件。
4.5 现象：文件上传成功但访问 404
原因：存储路径和静态资源映射路径不一致。解决：如果通过后端直接访问文件，需要配置WebMvcConfigurer把存储目录映射为静态资源路径；如果走 Nginx，确保 Nginx 的root或alias指向正确的目录，并且权限可读。
5. 二次开发：从能跑到好用，我改过的三个地方
5.1 增加文件类型白名单和大小校验
原项目可能只做了非空校验，生产环境必须加白名单。我一般会在FileStorageService.save开头加一段校验逻辑：
private static final List<String> ALLOWED_EXT = Arrays.asList("jpg", "jpeg", "png", "gif", "pdf", "doc", "docx", "xls", "xlsx", "zip"); public String save(MultipartFile file, String bizType) { String ext = StringUtils.getFilenameExtension(file.getOriginalFilename()); if (ext == null || !ALLOWED_EXT.contains(ext.toLowerCase())) { throw new IllegalArgumentException("不支持的文件类型: " + ext); } // 继续原有存储逻辑 }这样能挡住大部分恶意上传。大小校验在 Spring 配置里已经限制了，但业务层最好再判断一次，因为不同bizType可能有不同的大小要求。
5.2 把本地存储改成独立文件服务器
如果文件量大了，本地磁盘扛不住，就要把存储层抽出来。我的做法是定义一个StorageService接口，本地存储和远程存储各写一个实现类，通过配置切换。远程存储可以用 FTP、SFTP 或者对象存储的 SDK。下面是一个 FTP 实现的骨架：
@Service @ConditionalOnProperty(name = "file.storage.type", havingValue = "ftp") public class FtpStorageService implements StorageService { @Value("${file.ftp.host}") private String host; @Value("${file.ftp.port}") private int port; @Value("${file.ftp.username}") private String username; @Value("${file.ftp.password}") private String password; @Override public String save(MultipartFile file, String bizType) { // 连接 FTP，切换目录，上传流，返回远程路径 // 具体代码略，注意异常处理和连接池 } }这样改的好处是业务代码不用动，只加配置和实现类。切换存储介质时，改一行配置就行，不用重新编译。
5.3 上传接口加签名和过期时间
直接暴露上传接口有被滥用的风险。我通常会在上传前先请求一个签名接口，拿到一个带过期时间的 token，上传时带上这个 token，后端校验通过才允许写入。签名可以用 HMAC-SHA256，把bizType、时间戳、随机串拼起来算一个摘要。这样即使接口地址泄露，没有签名也传不了文件。
// 生成签名（前端或后端均可，建议后端生成） String sign = HmacUtils.hmacSha256Hex(secretKey, bizType + timestamp + nonce);后端校验时检查时间戳是否在有效期内（比如 5 分钟），nonce 是否已用过。这套机制能有效防止重放攻击和恶意上传。
5.4 验证改造是否生效
每次改完存储层或校验逻辑，我都会跑一遍回归：先用 Postman 传一个正常文件，确认能存能读；再传一个超大文件，确认被拦截；传一个.exe文件，确认被白名单挡住；传一个带../的文件名，确认路径穿越被防住。这四步走完，基本就稳了。
从那以后我每次接文件上传需求，都强制走一遍“Postman 先测后端 → 小程序真机联调 → 白名单和大小校验 → 签名防重放”的流程，再也没出现过上线后才发现上传失败的情况。希望帮到你。
本文还有配套的精品资源，点击获取
