GitLab CI中frontend-maven-plugin的npm包缓存不生效问题求助

问题根源排查 #

1. 缓存路径拼写错误
   你的.gitlab-ci.yml中缓存路径存在拼写错误：subsirectory1应为subdirectory1，这直接导致GitLab无法将缓存文件恢复到正确的目录，npm自然无法读取到缓存。

2. frontend-maven-plugin 工作目录与参数传递验证
   需确认frontend-maven-plugin的配置是否正确指定了工作目录，并传递了正确的缓存参数。如果工作目录设置错误，--cache .npm指定的相对路径会指向错误位置，导致缓存失效。

3. Docker容器内缓存目录权限问题
   GitLab Runner将缓存解压到Docker容器后，可能存在权限不足的情况，导致npm无法读取缓存文件。

分步解决方案 #

1. 修复缓存路径拼写错误 #

修改.gitlab-ci.yml中的缓存路径，纠正拼写错误：

build:
  stage: build
  tags:
    - devops
  cache:
    key: $CI_COMMIT_REF_SLUG
    paths:
      - my-web-module/src/main/webapp/subdirectory1/.npm
      - my-web-module/src/main/webapp/subdirectory2/.npm

2. 验证并修正 frontend-maven-plugin 配置 #

确保插件的每个执行步骤都正确设置了工作目录和npm参数，示例配置如下：

<plugin>
  <groupId>com.github.eirslett</groupId>
  <artifactId>frontend-maven-plugin</artifactId>
  <version>1.15.0</version>
  <executions>
    <!-- 安装Node和npm -->
    <execution>
      <id>install-node-npm</id>
      <goals>
        <goal>install-node-and-npm</goal>
      </goals>
      <configuration>
        <nodeVersion>v20.10.0</nodeVersion>
        <npmVersion>10.2.3</npmVersion>
      </configuration>
    </execution>
    <!-- subdirectory1 执行 npm ci -->
    <execution>
      <id>npm-ci-subdir1</id>
      <goals>
        <goal>npm</goal>
      </goals>
      <configuration>
        <workingDirectory>src/main/webapp/subdirectory1</workingDirectory>
        <arguments>ci --cache .npm --prefer-offline</arguments>
      </configuration>
    </execution>
    <!-- subdirectory1 执行 build -->
    <execution>
      <id>npm-build-subdir1</id>
      <goals>
        <goal>npm</goal>
      </goals>
      <configuration>
        <workingDirectory>src/main/webapp/subdirectory1</workingDirectory>
        <arguments>run build</arguments>
      </configuration>
    </execution>
    <!-- subdirectory2 同理 -->
    <execution>
      <id>npm-ci-subdir2</id>
      <goals>
        <goal>npm</goal>
      </goals>
      <configuration>
        <workingDirectory>src/main/webapp/subdirectory2</workingDirectory>
        <arguments>ci --cache .npm --prefer-offline</arguments>
      </configuration>
    </execution>
    <execution>
      <id>npm-build-subdir2</id>
      <goals>
        <goal>npm</goal>
      </goals>
      <configuration>
        <workingDirectory>src/main/webapp/subdirectory2</workingDirectory>
        <arguments>run build</arguments>
      </configuration>
    </execution>
  </executions>
</plugin>

3. 修复缓存目录权限 #

在流水线的before_script中添加权限修复命令，确保npm能读写缓存目录：

build:
  stage: build
  tags:
    - devops
  cache:
    key: $CI_COMMIT_REF_SLUG
    paths:
      - my-web-module/src/main/webapp/subdirectory1/.npm
      - my-web-module/src/main/webapp/subdirectory2/.npm
  before_script:
    - chmod -R 755 my-web-module/src/main/webapp/subdirectory1/.npm || true
    - chmod -R 755 my-web-module/src/main/webapp/subdirectory2/.npm || true
  script:
    - mvn clean package -DskipTests

4. 调试缓存恢复状态 #

添加调试命令验证缓存是否被正确恢复到容器内：

build:
  stage: build
  tags:
    - devops
  cache:
    key: $CI_COMMIT_REF_SLUG
    paths:
      - my-web-module/src/main/webapp/subdirectory1/.npm
      - my-web-module/src/main/webapp/subdirectory2/.npm
  before_script:
    # 查看缓存目录是否存在及内容
    - ls -la my-web-module/src/main/webapp/subdirectory1/
    - ls -la my-web-module/src/main/webapp/subdirectory2/
  script:
    - mvn clean package -DskipTests

5. 备选方案：使用全局npm缓存 #

如果上述方案仍不生效，可以改用npm全局缓存目录进行缓存，避免相对路径问题：

build:
  stage: build
  tags:
    - devops
  cache:
    key: $CI_PROJECT_ID-$CI_COMMIT_REF_SLUG
    paths:
      - ~/.npm
  script:
    # 移除npm命令中的--cache参数，使用默认全局缓存
    - mvn clean package -DskipTests

这里缓存key加入$CI_PROJECT_ID是为了避免不同项目的缓存冲突。

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