Spring MVC文件下载提示检查网络连接：错误排查与问题分析

核心错误点及原因分析 #

1. 下载方法返回视图名称导致响应冲突 #

FileController的downloadFile方法最后返回"home"视图，但此时已经向response.getOutputStream()写入了文件内容。Spring会同时处理视图渲染和流输出，导致响应格式混乱，浏览器无法正确解析，误以为是网络问题。

2. 硬编码Content-Type限制所有文件为PDF #

代码固定设置response.setContentType("application/pdf")，若上传的不是PDF文件，浏览器无法识别文件类型，触发下载失败提示。

3. 文件名分割逻辑存在数组越界风险 #

addNewFile方法中用newName.split("[.\\s]+")分割文件名，若原文件名包含多个点（如file.v2.pdf），分割后的数组长度超过预期，saveNewFile中取newFile[1]和newFile[2]会抛出异常，导致文件元数据存储错误，进而下载时找不到正确文件路径。

4. 自定义findById方法存在空指针风险 #

FileRepository自定义的findById(long id)找不到文件时返回null，后续调用fileEntity.getUuid()会直接抛出空指针，导致请求中断，浏览器收到错误响应后提示网络问题。

5. 文件存储路径选择不合理 #

将文件存在src/main/resources/images/目录，该目录打包后会进入jar包，无法通过Files API直接访问（生产环境尤其明显），且开发环境中IDE可能自动刷新该目录，导致文件丢失或路径失效。

修复方案 #

1. 修改下载方法的返回逻辑 #

将downloadFile方法返回值改为void，避免视图渲染与流输出冲突：

@GetMapping("/download/{fileId}")
public void downloadFile(@PathVariable(value = "fileId") long fileId, HttpServletResponse response) {
    Optional<FileEntity> fileEntityOpt = fileRepository.findById(fileId);
    if (fileEntityOpt.isEmpty()) {
        response.setStatus(HttpServletResponse.SC_NOT_FOUND);
        return;
    }
    FileEntity fileEntity = fileEntityOpt.get();
    
    Path file = Paths.get(UPLOAD_FOLDER, fileEntity.getUuid() + "." + fileEntity.getName());
    if (!Files.exists(file)) {
        response.setStatus(HttpServletResponse.SC_NOT_FOUND);
        return;
    }
    
    // 动态获取文件ContentType
    String contentType = Files.probeContentType(file);
    response.setContentType(contentType != null ? contentType : "application/octet-stream");
    // 编码文件名避免特殊字符问题
    String encodedFilename = URLEncoder.encode(fileEntity.getName(), StandardCharsets.UTF_8.toString());
    response.addHeader("Content-Disposition", "attachment; filename=\"" + encodedFilename + "\"; filename*=UTF-8''" + encodedFilename);
    
    try (OutputStream out = response.getOutputStream()) {
        Files.copy(file, out);
        out.flush();
    } catch (IOException ex) {
        ex.printStackTrace();
        response.setStatus(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
    }
}

2. 修复文件名分割逻辑 #

改用安全方式提取原文件名和扩展名：

@PostMapping("/")
public String addNewFile(@RequestParam(value = "file", required = false) MultipartFile multipart, Model model) {
    if (multipart == null || multipart.isEmpty()) {
        model.addAttribute("error", "请选择要上传的文件");
        return "home";
    }
    
    try {
        String uuid = UUID.randomUUID().toString();
        String originalFilename = multipart.getOriginalFilename();
        String extension = "";
        int dotIndex = originalFilename.lastIndexOf('.');
        if (dotIndex > 0) {
            extension = originalFilename.substring(dotIndex);
        }
        String newName = uuid + extension;
        
        Path path = Paths.get(UPLOAD_FOLDER + newName);
        Files.write(path, multipart.getBytes());
        
        FileEntity file = new FileEntity();
        file.setName(originalFilename);
        file.setPath(UPLOAD_FOLDER);
        file.setUuid(uuid);
        fileService.saveNewFile(file);
        
    } catch (IOException exception) {
        exception.printStackTrace();
        model.addAttribute("error", "文件上传失败");
    }
    
    model.addAttribute("files", fileService.getAllFiles());
    return "home";
}

同时修改FileService的saveNewFile方法：

public FileEntity saveNewFile(FileEntity file) {
    return fileRepository.save(file);
}

3. 修复Repository的findById方法 #

删除自定义findById，使用JpaRepository自带的Optional返回方法：

@Repository
public interface FileRepository extends JpaRepository<FileEntity, Long> {
    // 移除自定义findById，使用父接口的Optional<FileEntity> findById(Long id);
}

FileService中对应修改：

public Optional<FileEntity> findById(long id) {
    return fileRepository.findById(id);
}

4. 调整文件存储路径 #

改用项目外部独立目录，比如：

private static String UPLOAD_FOLDER = "C://Users//SystemX//uploaded_files//";

并在启动时自动创建目录：

@PostConstruct
public void init() {
    Path uploadPath = Paths.get(UPLOAD_FOLDER);
    if (!Files.exists(uploadPath)) {
        try {
            Files.createDirectories(uploadPath);
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

浏览器提示“检查网络连接”的具体原因 #

当下载请求出现以下情况时，浏览器会误判为网络问题：

• 服务器返回响应格式混乱（同时返回视图HTML和文件流）
• 响应状态码异常（如500错误，但浏览器未正确解析）
• 文件流未完整输出，连接提前中断
• 响应头设置错误（如Content-Type不匹配，导致浏览器无法处理响应）

修复上述问题后，确保响应仅输出文件流、状态码正确、文件路径有效，即可解决该提示问题。

内容的提问来源于stack exchange，提问作者Maksim1251