GeoServer在CentOS部署中文乱码显示方框终极解决方案

问题背景

在CentOS服务器上部署GeoServer，使用Tomcat作为应用服务器，SLD样式中的中文标签显示为方框□。虽然已经设置了-Dfile.encoding=UTF-8，但问题依旧存在。

环境信息

操作系统: CentOS 7/8
Java版本: OpenJDK 11
应用服务器: Apache Tomcat 9
GIS服务器: GeoServer 2.x

问题原因分析

中文显示方框通常由以下原因导致：

缺少中文字体 - 系统没有安装中文字体文件
字体路径问题 - Java无法找到已安装的字体
编码设置不完整 - 仅设置文件编码不够
SLD配置问题 - 指定的字体在系统中不存在

完整解决方案

一、安装中文字体（核心步骤）

1.1 安装文泉驿字体（推荐）

bash 复制代码

# 更新系统包
sudo yum update -y

# 安装文泉驿字体
sudo yum install -y wqy-microhei-fonts

# 刷新字体缓存
sudo fc-cache -fv

1.2 验证字体安装

bash 复制代码

# 查看已安装的中文字体
fc-list | grep -i "hei\|song\|yahei"

# 如果看到类似输出，说明安装成功
# /usr/share/fonts/wqy-microhei/wqy-microhei.ttc: WenQuanYi Micro Hei,文泉驛微米黑:style=Regular

二、配置Java环境变量（关键步骤）

2.1 修改JAVA_OPTS

编辑你的Java启动配置文件（~/.bashrc、/etc/profile、setenv.sh或Tomcat启动脚本）：

bash 复制代码

# 原来的配置
export JAVA_OPTS="-Xms512m -Xmx2048m -XX:+UseG1GC -Dfile.encoding=UTF-8"

# 修改后的配置（添加三个关键参数）
export JAVA_OPTS="-Xms512m -Xmx2048m -XX:+UseG1GC -Dfile.encoding=UTF-8 -Djava.awt.headless=true -Duser.language=zh -Duser.region=CN"

参数解释：

-Dfile.encoding=UTF-8 - 设置文件编码为UTF-8
-Djava.awt.headless=true - 关键：启用headless模式，允许在没有显示设备的环境下进行字体渲染
-Duser.language=zh -Duser.region=CN - 设置默认语言环境为中文

2.2 应用配置

bash 复制代码

# 使配置生效
source ~/.bashrc

# 验证配置
echo $JAVA_OPTS

三、修改SLD样式文件

3.1 简化字体配置

在SLD的<Font>标签中，使用最简单的字体配置：

xml 复制代码

<Font>
  <!-- 只指定一个确保存在的字体 -->
  <CssParameter name="font-family">'WenQuanYi Micro Hei'</CssParameter>
  <CssParameter name="font-size">12</CssParameter>
  <CssParameter name="font-weight">bold</CssParameter>
</Font>

3.2 完整SLD示例

xml 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<StyledLayerDescriptor version="1.0.0"
  xmlns="http://www.opengis.net/sld"
  xmlns:ogc="http://www.opengis.net/ogc">
  
  <NamedLayer>
    <Name>point_style</Name>
    <UserStyle>
      <Title>中文点样式</Title>
      
      <FeatureTypeStyle>
        <!-- 点符号 -->
        <Rule>
          <PointSymbolizer>
            <Graphic>
              <Mark>
                <WellKnownName>circle</WellKnownName>
                <Fill>
                  <CssParameter name="fill">#FF0000</CssParameter>
                </Fill>
                <Stroke>
                  <CssParameter name="stroke">#FFFFFF</CssParameter>
                  <CssParameter name="stroke-width">2</CssParameter>
                </Stroke>
              </Mark>
              <Size>10</Size>
            </Graphic>
          </PointSymbolizer>
        </Rule>
        
        <!-- 中文标签 -->
        <Rule>
          <TextSymbolizer>
            <Label>
              <ogc:PropertyName>name</ogc:PropertyName>
            </Label>
            <Font>
              <CssParameter name="font-family">'WenQuanYi Micro Hei'</CssParameter>
              <CssParameter name="font-size">12</CssParameter>
              <CssParameter name="font-weight">bold</CssParameter>
            </Font>
            <LabelPlacement>
              <PointPlacement>
                <AnchorPoint>
                  <AnchorPointX>0.5</AnchorPointX>
                  <AnchorPointY>0</AnchorPointY>
                </AnchorPoint>
                <Displacement>
                  <DisplacementX>0</DisplacementX>
                  <DisplacementY>15</DisplacementY>
                </Displacement>
              </PointPlacement>
            </LabelPlacement>
            <Fill>
              <CssParameter name="fill">#000000</CssParameter>
            </Fill>
          </TextSymbolizer>
        </Rule>
      </FeatureTypeStyle>
    </UserStyle>
  </NamedLayer>
</StyledLayerDescriptor>

四、重启Tomcat服务

4.1 重启命令

bash 复制代码

# 如果使用systemd管理
sudo systemctl restart tomcat

# 如果手动管理
cd /usr/local/tomcat/bin
./shutdown.sh
./startup.sh

4.2 查看启动日志

bash 复制代码

# 实时查看日志
tail -f /usr/local/tomcat/logs/catalina.out

# 检查是否有错误信息
grep -i "font\|encoding\|error" /usr/local/tomcat/logs/catalina.out

五、验证解决方案

5.1 在GeoServer中测试

登录GeoServer管理界面
打开图层预览
选择使用修改后的SLD样式
查看中文标签是否正常显示

六、故障排除

问题1：字体已安装但仍显示方框

bash 复制代码

# 检查Java是否能访问字体
java -cp . TestFonts

# 确保字体文件权限正确
sudo chmod 644 /usr/share/fonts/wqy-microhei/*

# 检查Tomcat运行用户是否有字体目录访问权限
sudo chown -R tomcat:tomcat /usr/share/fonts/wqy-microhei/

问题2：重启后配置失效

bash 复制代码

# 检查Tomcat启动脚本
cat /usr/local/tomcat/bin/catalina.sh | grep JAVA_OPTS

# 在catalina.sh中添加（如果通过脚本启动）
JAVA_OPTS="$JAVA_OPTS -Djava.awt.headless=true -Duser.language=zh"

问题3：特定图层中文不正常

检查数据源编码（确保数据库/Shapefile为UTF-8）
检查WMS请求参数：&charset=UTF-8
在GeoServer中设置服务字符集：
- 进入"全局设置" → "服务"
- 设置字符集为"UTF-8"

七、一键解决脚本

创建 fix_geoserver_chinese.sh 脚本：

bash 复制代码

#!/bin/bash
echo "========================================"
echo "GeoServer 中文显示问题修复脚本"
echo "========================================"

# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
NC='\033[0m' # No Color

# 1. 安装字体
echo -e "\n${GREEN}[1/4] 安装中文字体...${NC}"
if ! rpm -q wqy-microhei-fonts > /dev/null 2>&1; then
    sudo yum install -y wqy-microhei-fonts
    echo "✓ 文泉驿字体安装完成"
else
    echo "✓ 文泉驿字体已安装"
fi

# 2. 刷新字体缓存
echo -e "\n${GREEN}[2/4] 刷新字体缓存...${NC}"
sudo fc-cache -fv > /dev/null 2>&1
echo "✓ 字体缓存已刷新"

# 3. 配置Java参数
echo -e "\n${GREEN}[3/4] 配置Java环境...${NC}"
if ! grep -q "java.awt.headless=true" ~/.bashrc; then
    sed -i '/JAVA_OPTS=.*/s/"$/ -Djava.awt.headless=true -Duser.language=zh -Duser.region=CN"/' ~/.bashrc
    echo "✓ Java参数已更新"
else
    echo "✓ Java参数已配置"
fi

source ~/.bashrc

# 4. 重启Tomcat
echo -e "\n${GREEN}[4/4] 重启Tomcat服务...${NC}"
if systemctl is-active --quiet tomcat; then
    sudo systemctl restart tomcat
    echo "✓ Tomcat已重启"
else
    echo "⚠ Tomcat未运行，请手动启动"
fi

echo -e "\n${GREEN}========================================"
echo "修复完成！请执行以下操作："
echo "1. 修改SLD字体为：'WenQuanYi Micro Hei'"
echo "2. 在GeoServer中重新加载样式"
echo "3. 清除浏览器缓存后测试"
echo "========================================${NC}"

赋予执行权限并运行：

bash 复制代码

chmod +x fix_geoserver_chinese.sh
./fix_geoserver_chinese.sh

八、最佳实践建议

字体选择优先顺序：
- 首选：'WenQuanYi Micro Hei'（文泉驿微米黑）
- 备选：'Noto Sans CJK SC'（思源黑体）
- 兼容：sans-serif（系统无衬线字体）

Java参数优化：

bash 复制代码

# 生产环境推荐配置
export JAVA_OPTS="-server -Xms2g -Xmx4g -XX:+UseG1GC 
                  -Dfile.encoding=UTF-8 
                  -Djava.awt.headless=true 
                  -Duser.language=zh 
                  -Duser.region=CN 
                  -Djava.security.egd=file:/dev/./urandom"

SLD编写规范：
- 始终指定字体族（font-family）
- 避免使用中文标点符号作为字体名分隔符
- 为不同操作系统提供字体回退
监控与维护：
- 定期检查catalina.out日志中的字体相关错误
- 备份SLD样式文件
- 记录字体安装位置和版本

总结

通过以上步骤，GeoServer中文显示方框问题可以得到彻底解决。核心要点包括：

安装中文字体 - 确保系统有可用的中文字体
配置Java参数 - 添加headless模式和语言环境设置
修改SLD配置 - 使用系统实际存在的字体名称
重启服务验证 - 确保所有配置生效

按照本文的步骤操作，99%的中文显示问题都能得到解决。如果仍有问题，请检查Tomcat日志中的具体错误信息，或考虑更新Java版本。

作者经验 ：在生产环境中，大多数中文显示问题都是由于缺少-Djava.awt.headless=true参数导致的。即使安装了字体，没有这个参数，Java也无法在服务器环境下正确渲染文字。

最后提示：修改配置后一定要重启Tomcat服务，并清除浏览器缓存进行测试。