本文详解 Spring Boot 项目中通过 Thymeleaf 渲染 Base64 编码图像时常见的 EL 表达式语法错误，提供三种合规写法并说明原理，避免因表达式嵌套（如 *{...${...}...}）导致的 SpelParseException 异常。

本文详解 spring boot 项目中通过 thymeleaf 渲染 base64 编码图像时常见的 el 表达式语法错误，提供三种合规写法并说明原理，避免因表达式嵌套（如 `*{...${...}...}`）导致的 `spelparseexception` 异常。

在 Spring Boot + Thymeleaf 应用中，将用户上传的图片以 Base64 形式嵌入 HTML 是常见需求。典型流程是：后端将 byte[] 图片数据通过 Base64.getEncoder().encodeToString() 转为字符串，并存入 Model；前端则需在 <img> 标签中拼接 data:image/xxx;base64,${encodedImage} 数据 URI。但许多开发者会误用 Thymeleaf 的表达式语法，例如：

<!-- ❌ 错误写法：禁止嵌套表达式 -->
<img th:src="*{'data:image/jpeg;base64,'+ ${encodedImage}}" alt="Profile Picture">

该写法触发了 SpelParseException: EL1041E，根本原因在于 Thymeleaf 不支持在 *{...}（选择表达式，用于表单绑定）内嵌套 ${...}（变量表达式）。*{} 仅用于对象属性访问（如 *{user.name}），不可用于字符串拼接。

✅ 正确做法是统一使用变量表达式 ${...} 或字面量替换 |...|，推荐以下三种等效且安全的写法：

方式一：字面量替换（推荐｜语义清晰、无转义风险）

<img th:src="|data:image/jpeg;base64,${encodedImage}|" alt="Profile Picture" />

方式二：字符串拼接（使用单引号包裹字面量）

<img th:src="'data:image/jpeg;base64,' + ${encodedImage}" alt="Profile Picture" />

方式三：完整 SpEL 表达式（显式包裹）

<img th:src="${'data:image/jpeg;base64,' + encodedImage}" alt="Profile Picture" />

⚠️ 注意事项：

• 若图片类型不确定（如 PNG、GIF），建议根据数据库中存储的 MIME 类型动态设置 image/xxx，例如：<img th:src="|data:${user.profilePictureMimeType};base64,${encodedImage}|">；
• 确保后端 encodedImage 非空，否则前端会渲染无效 data URI，可添加 Thymeleaf 条件判断：

  <img th:if="${not #strings.isEmpty(encodedImage)}" 
       th:src="|data:image/jpeg;base64,${encodedImage}|" 
       alt="Profile Picture" />

• 对于大图，Base64 编码体积约膨胀 33%，可能影响页面加载性能，生产环境建议优先使用静态资源服务或 CDN。

综上，Thymeleaf 的表达式语法有明确语义边界，切勿混用 *{} 和 ${}。掌握 |...| 字面量替换这一简洁写法，既能提升可读性，又能规避解析异常，是构建健壮模板的最佳实践。