Java Web中用OutputStreamWriter写模板渲染结果时，必须显式指定UTF-8编码并确保与Content-Type中charset一致，同时配置模板引擎默认编码为UTF-8，推荐用try-with-resources自动管理资源。
在 Java Web 开发中，使用 OutputStreamWriter 将模板引擎（如 FreeMarker、Thymeleaf、Velocity）渲染结果写入 HTTP 响应流时，**编码必须显式指定，且需与响应的 Content-Type 中声明的字符集一致**，否则会出现中文乱码或 UnsupportedEncodingException 异常。
确保响应头已设置正确的字符集
在获取输出流前，先调用 response.setCharacterEncoding("UTF-8")，并设置 Content-Type（含 charset）：
response.setCharacterEncoding("UTF-8");-
response.setContentType("text/html;charset=UTF-8");（或application/json;charset=UTF-8等）
这一步影响后续 response.getWriter() 的默认编码，也间接约束 OutputStreamWriter 的行为 —— 虽然它不读取响应头，但服务端和浏览器需统一编码才能正确显示。
用指定编码构造 OutputStreamWriter
不要依赖平台默认编码，始终传入明确的字符集名称（推荐 "UTF-8"）：
立即学习“Java免费学习笔记（深入）”；
deep-java-review
下载
Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...
new OutputStreamWriter(response.getOutputStream(), "UTF-8")- 避免使用
new OutputStreamWriter(response.getOutputStream())（会用 JVM 默认编码，通常不是 UTF-8） - 字符集名必须是 JDK 支持的标准名称，如
"UTF-8"、"ISO-8859-1"，不能写成"utf8"或"utf-8"（部分旧 JDK 对大小写敏感）
注意模板引擎自身的编码配置
仅设置 OutputStreamWriter 编码还不够，模板引擎也要匹配：
-
FreeMarker：配置
Configuration.setDefaultEncoding("UTF-8")，并确保模板文件本身保存为 UTF-8 -
Thymeleaf：在
TemplateResolver中设setCharacterEncoding("UTF-8") -
Velocity：通过
VelocityEngine.setProperty("input.encoding", "UTF-8")和"output.encoding"
否则模板解析阶段就可能产生乱码，Writer 再怎么指定编码也无力回天。
关闭顺序与异常处理
写完后务必正确关闭 OutputStreamWriter（它会自动刷新并关闭底层 OutputStream），但要注意：
- 不要手动调用
response.getOutputStream().close()—— 这会导致容器后续无法写入响应头或提交状态码 - 推荐用 try-with-resources：
try (OutputStreamWriter writer = new OutputStreamWriter(response.getOutputStream(), "UTF-8")) {
template.process(data, writer); // 如 FreeMarker 的 Template.process()
}
这样既保证资源释放，又避免干扰 Servlet 容器对响应流的管理。
