Java中中文编码处理：URLEncoder与URLDecoder详解

本文深入剖析了Java中处理中文URL编码的常见误区与最佳实践，明确指出URLEncoder和URLDecoder仅适用于表单参数值或独立路径段的编码解码，绝不能直接用于整个URL——否则会将关键分隔符（如/、:、?）错误转义，导致404、400或500等严重路由异常；文章强调应优先使用java.net.URI类自动、合规地处理URL各组成部分，并厘清框架（如Spring Boot）已自动完成的解码环节，避免重复解码引发乱码或异常，真正难点在于精准识别编码边界与处理层级，而非编码本身。

URLEncoder 和 URLDecoder 不是用来处理网页路径的，强行用它们编码/解码路径会导致 404 或 500 错误。

URLEncoder.encode() 会把 / 变成 %2F，破坏 URL 路径结构

很多人以为对整个 URL 调用 URLEncoder.encode() 就能“安全传输中文”，结果发现跳转 404、Nginx 返回 400、Spring Boot 报 IllegalArgumentException: Invalid character in path——根本原因就是它把路径分隔符 /、冒号 :、问号 ? 全部编码了。

• URLEncoder.encode("https://example.com/用户/订单?id=张三", "UTF-8") → https%3A%2F%2Fexample.com%2F%E7%94%A8%E6%88%B7%2F%E8%AE%A2%E5%8D%95%3Fid%3D%E5%BC%A0%E4%B8%89（整个 URL 变成一串不可路由的字符串）
• 正确做法：只对路径段（path segment）或查询参数值单独编码，比如 "用户" → %E7%94%A8%E6%88%B7，而不是对 /用户/ 整体编码
• Java 里推荐用 java.net.URI 构造器自动处理路径编码，它内部按 RFC 3986 区分 scheme、host、path、query，只编码该编码的部分

URLDecoder.decode() 解码失败常因字符集不匹配或过度解码

收到一个含中文的请求路径如 /api/search?keyword=%E6%9D%AD%E5%B7%9E，用 URLDecoder.decode(keyword, "UTF-8") 是对的；但如果后端框架（如 Spring MVC）已自动解码过一次，你再手动调一次 URLDecoder.decode()，就会出现 NumberFormatException 或乱码——因为 %E6%9D%AD 已变成汉字“杭”，再次解码就报错。

• Spring Boot 默认对 query param 和 form data 自动 URL-decode，@RequestParam String keyword 拿到的就是已解码的字符串，无需再调 URLDecoder.decode()
• 只有在读取原始请求 URI（如 HttpServletRequest.getRequestURI()）时才可能拿到未解码的字符串，这时才需手动 decode，且必须指定 "UTF-8"，不能用平台默认编码
• 若解码抛 IllegalArgumentException: URLDecoder: Illegal hex characters，说明传入字符串里混入了非 %xx 格式的非法内容，应先过滤或校验

现代 Java 应该优先用 java.net.URI 而不是 URLEncoder

直接拼接字符串 + URLEncoder 是容易出错的老套路。URI 类在构造时就做合规编码，还能避免手滑漏掉某一段。

• 构建带中文路径的 URL：

  URI uri = new URI("https", "api.example.com", "/搜索/结果", "q=" + URLEncoder.encode("Java教程", "UTF-8"), null);
  String url = uri.toString(); // 自动编码 path 中的中文，保留 / 和 ? 的语义

• 解析并安全获取路径段：

  URI uri = new URI(request.getRequestURI());
  List pathSegments = Arrays.asList(uri.getPath().split("/"));
  String decodedSegment = URLDecoder.decode(pathSegments.get(2), "UTF-8"); // 只解码具体段

• URLEncoder 是为 application/x-www-form-urlencoded 设计的（表单提交），不是为通用 URL 路径设计的

真正难的不是怎么编码，而是分清哪部分是路径、哪部分是参数、哪部分已被框架处理过。多一层 decode 或少一层 encode，都可能让中文在某个环节变成 %E4%BD%A0%E5%A5%BD 或 浣犲ソ ——而问题往往出现在日志里看不到的中间层。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Java中中文编码处理：URLEncoder与URLDecoder详解》文章吧，也可关注golang学习网公众号了解相关技术文章。