005-SpringSecurity-Demo 配置外部文件映射

SpringSecurity-Demo 配置外部文件映射

- 一、需求说明
- 二、实现步骤
- - [1. 定义配置属性类（读取yml配置）](#1. 定义配置属性类（读取yml配置）)
  - [2. 编写资源映射配置](#2. 编写资源映射配置)
  - [3. application.yml 配置（路径可自定义）](#3. application.yml 配置（路径可自定义）)
- 三、原理讲解（一看就懂）
- 四、使用示例
- 五、路径写法说明
- - [1. 相对路径](#1. 相对路径)
  - [2. Windows 绝对路径](#2. Windows 绝对路径)
  - [3. Linux 绝对路径](#3. Linux 绝对路径)
- 六、常见问题
- - [1. 访问404](#1. 访问404)
  - [2. 不想用profile作为URL前缀](#2. 不想用profile作为URL前缀)
  - [3. 映射网络路径？](#3. 映射网络路径？)

在 Spring Boot 项目开发中，我们经常需要上传图片、文档等文件，并希望通过浏览器地址直接访问（比如头像、附件预览）。

但直接把文件存在项目内部会导致打包过大、更新不便，所以最佳实践是：文件存在外部文件夹，通过 Spring MVC 资源映射实现外网访问。

本篇博客就带你一步步实现：外部文件目录 → 浏览器在线访问，完全适配 Spring Boot 3.2.4 + JDK 21，代码可直接复制用于生产环境。

一、需求说明

我们要实现的功能非常简单实用：

把文件存在项目根目录的 ./file 文件夹（实际使用可配置其它目录）
通过地址 http://localhost:5826/profile/xxx.png 直接访问图片
路径可配置，不写死代码

二、实现步骤

代码已推送至 Gitee 仓库：springdecurity-demo

1. 定义配置属性类（读取yml配置）

专门用来读取外部配置，代码解耦、规范优雅。

java 复制代码

package com.junjiu.springboot3.config.properties;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

/**
 * program: security-demo
 * ClassName: JunjiuCustomProperties
 * description:
 *
 * @author: 君九
 * @create: 2026-04-03 14:35
 * @version: 1.0
 **/
@Data
@Component
@ConfigurationProperties(prefix = "junjiu.custom")
public class JunjiuCustomProperties {

    /**
     * 外部资源存储路径
     * 例如：./file
     */
    private String resourcePath;
}

2. 编写资源映射配置

继承 WebMvcConfigurer，重写 addResourceHandlers 实现外部文件夹映射到URL。

java 复制代码

package com.junjiu.springboot3.config;

import com.junjiu.springboot3.config.properties.JunjiuCustomProperties;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * 外部资源映射配置
 * 实现：外部文件夹 -> 浏览器URL访问
 */
@Configuration
public class ResourceConfig implements WebMvcConfigurer {

    @Autowired
    private JunjiuCustomProperties junjiuCustomProperties;

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 从配置文件读取路径
        String resourcePath = junjiuCustomProperties.getResourcePath();

        // 确保路径以 / 结尾，避免拼接错误
        if (!resourcePath.endsWith("/")) {
            resourcePath += "/";
        }

        System.out.println("外部资源路径：" + resourcePath);

        // 映射规则：
        // 浏览器访问 /profile/**  →  找本地 file:xxx 目录
        registry.addResourceHandler("/profile/**")
                .addResourceLocations("file:" + resourcePath);
    }
}

3. application.yml 配置（路径可自定义）

yaml 复制代码

junjiu:
  custom:
    resource-path: ./file  # 相对路径，项目根目录下的 file 文件夹

三、原理讲解（一看就懂）

java 复制代码

registry.addResourceHandler("/profile/**")
        .addResourceLocations("file:" + resourcePath);

作用：

当你访问：http://localhost:5826/profile/avatar.jpg
Spring Boot 就会去：项目根目录/file/avatar.jpg 找图片
找到就直接显示，找不到返回404

✅ 支持：

图片（png/jpg/gif）
文档（pdf/txt）
视频（mp4）
音频（mp3）

四、使用示例

在项目根目录创建 file 文件夹
放入一张图片 xr.jpg
启动项目
浏览器访问：

http://localhost:5826/profile/xr.jpg

✅ 直接显示图片！

五、路径写法说明

1. 相对路径

yaml 复制代码

resource-path: ./file

表示：项目根目录/file

2. Windows 绝对路径

yaml 复制代码

resource-path: D:/upload/file

3. Linux 绝对路径

yaml 复制代码

resource-path: /home/server/upload

六、常见问题

1. 访问404

检查文件夹是否创建
检查文件名大小写
检查路径是否以 / 结尾
重启项目

2. 不想用profile作为URL前缀

修改这里即可：

java 复制代码

addResourceHandler("/files/**")

访问地址变成：

复制代码

http://localhost:5826/files/test.jpg

3. 映射网络路径？

支持，但需要权限和共享目录。

代码已推送至 Gitee 仓库：springdecurity-demo
若有转载，请标明出处：