Gradle Docker镜像无法在.gradle目录创建文件的问题咨询

我尝试使用Gradle Docker镜像（gradle:8.5-jdk21-alpine）构建项目，想要通过写入~/.gradle/gradle.properties来配置仓库URL及凭据，但发现无法在.gradle目录下创建任何文件。以下是测试用的Dockerfile及运行输出：

测试Dockerfile #

FROM gradle:8.5-jdk21-alpine

RUN ls -la .
RUN echo hello > out
RUN ls -la .
WORKDIR .gradle
RUN ls -la .
RUN echo world > out
RUN ls -la .

运行输出 #

Step 1/8 : FROM gradle:8.5-jdk21-alpine
 ---> 5d527d32c7be
Step 2/8 : RUN ls -la .
 ---> Running in 5195db2c8c4f
total 12
drwxr-srwx    1 gradle   gradle        4096 Jan 27 08:42 .
drwxr-xr-x    1 root     root          4096 Jan 27 08:42 ..
drwxr-srwx    2 gradle   gradle        4096 Jan 27 08:42 .gradle
 ---> Removed intermediate container 5195db2c8c4f
 ---> 18666307c9c5
Step 3/8 : RUN echo hello > out
 ---> Running in b7f9dfb48848
 ---> Removed intermediate container b7f9dfb48848
 ---> 0dded2505644
Step 4/8 : RUN ls -la .
 ---> Running in 7c7342768fd0
total 16
drwxr-srwx    1 gradle   gradle        4096 Feb  9 17:02 .
drwxr-xr-x    1 root     root          4096 Jan 27 08:42 ..
drwxr-srwx    2 gradle   gradle        4096 Jan 27 08:42 .gradle
-rw-r--r--    1 root     gradle           6 Feb  9 17:02 out
 ---> Removed intermediate container 7c7342768fd0
 ---> a50b7ebba4f3
Step 5/8 : WORKDIR .gradle
 ---> Running in d2fc92439198
 ---> Removed intermediate container d2fc92439198
 ---> 1537b03de558
Step 6/8 : RUN ls -la .
 ---> Running in 68e6257e2cc3
total 8
drwxr-srwx    2 gradle   gradle        4096 Jan 27 08:42 .
drwxr-srwx    1 gradle   gradle        4096 Feb  9 17:02 ..
 ---> Removed intermediate container 68e6257e2cc3
 ---> 9ac58a7ff572
Step 7/8 : RUN echo world > out
 ---> Running in 41543dabd95f
 ---> Removed intermediate container 41543dabd95f
 ---> ca7b08f161fc
Step 8/8 : RUN ls -la .
 ---> Running in 27d1c45d32b6
total 8
drwxr-srwx    2 gradle   gradle        4096 Jan 27 08:42 .
drwxr-srwx    1 gradle   gradle        4096 Feb  9 17:02 ..
 ---> Removed intermediate container 27d1c45d32b6
 ---> a7ef272b3325

问题解答 #

1. 无法写入的原因 #

.gradle目录是Gradle官方镜像中预定义的匿名卷。Docker构建阶段（RUN指令执行）中，卷的内容不会被持久化到镜像层——所有对卷内的写入操作仅作用于临时卷实例，当前RUN指令的容器销毁后，写入内容会直接丢失，不会保留到最终镜像。

2. 目录的特殊处理 #

Gradle官方镜像的Dockerfile将/home/gradle/.gradle声明为匿名卷，核心目的：

• 避免构建缓存（依赖包、构建产物）被打包进镜像，大幅减小镜像体积
• 支持运行容器时挂载本地目录/命名卷，实现缓存复用，加速后续构建

3. 为何未报错 #

当前用户gradle对.gradle目录拥有读写权限，Docker允许对卷进行写入操作，因此echo world > out执行时无权限错误。但由于卷的特性，写入的文件仅存在于当前RUN指令的临时容器中，容器被清理后文件消失，后续ls自然无法看到。

4. 传递仓库凭据的规范方式 #

方式1：构建时通过--build-arg注入（不推荐公共镜像）

通过构建参数生成临时gradle.properties，注意不要将含凭据的镜像推送到公共仓库：

FROM gradle:8.5-jdk21-alpine
ARG REPO_URL
ARG REPO_USERNAME
ARG REPO_PASSWORD
RUN echo "mavenRepo.url=${REPO_URL}" > /home/gradle/.gradle/gradle.properties && \
    echo "mavenRepo.username=${REPO_USERNAME}" >> /home/gradle/.gradle/gradle.properties && \
    echo "mavenRepo.password=${REPO_PASSWORD}" >> /home/gradle/.gradle/gradle.properties

构建命令：

docker build --build-arg REPO_URL=xxx --build-arg REPO_USERNAME=xxx --build-arg REPO_PASSWORD=xxx -t my-gradle-image .

方式2：运行时挂载本地配置文件

将本地已配置好的gradle.properties挂载到容器对应目录：

docker run -v /path/to/local/gradle.properties:/home/gradle/.gradle/gradle.properties gradle:8.5-jdk21-alpine gradle build

方式3：环境变量传递（推荐）

Gradle支持通过前缀为ORG_GRADLE_PROJECT_的环境变量覆盖配置，无需修改镜像，安全性更高：

docker run -e ORG_GRADLE_PROJECT_mavenRepoUrl=xxx -e ORG_GRADLE_PROJECT_mavenRepoUsername=xxx -e ORG_GRADLE_PROJECT_mavenRepoPassword=xxx gradle:8.5-jdk21-alpine gradle build

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