大型多层Maven项目执行mvn install时UTF-8编码不可映射字符问题

核心原因 #

这类错误本质是构建环节编码不统一：文件实际编码、Maven编译编码、JVM默认编码三者不一致，导致像“é”这类字符在转码时出现不可映射或乱码（变为“?”）。

快速解决方案（按优先级排序） #

1. 统一Maven项目编码配置（推荐） #

在项目父pom.xml中添加全局编码配置，让所有子模块继承：

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
</properties>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <encoding>${project.build.sourceEncoding}</encoding>
                </configuration>
            </plugin>
        </plugins>
    </pluginManagement>
</build>

单个模块直接在对应pom.xml中添加上述配置即可。

2. 临时设置JVM编码环境变量 #

执行mvn install前先设置JVM编码参数，强制Maven用UTF-8编译：

export JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8"
mvn clean install

Docker构建时，将这条命令加到Dockerfile的构建步骤：

RUN export JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8" && mvn clean install

3. 批量修正文件编码（如果文件本身编码错误） #

若代码文件实际为ISO-8859-1等非UTF-8编码，用iconv批量转换：

# 检查文件编码示例
file src/main/java/com/example/YourClass.java

# 批量将ISO-8859-1编码的.java文件转为UTF-8
find . -name "*.java" -exec iconv -f ISO-8859-1 -t UTF-8 {} -o {} \;

注意：转换前建议备份代码，避免意外。

4. 全局配置Maven编码 #

修改用户目录下的~/.m2/settings.xml，添加全局编码profile，所有Maven项目生效：

<settings>
    <profiles>
        <profile>
            <id>utf8-encoding</id>
            <properties>
                <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
                <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
            </properties>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>utf8-encoding</activeProfile>
    </activeProfiles>
</settings>

内容的提问来源于stack exchange，提问作者Calamity