Bitbucket DC 8.18中Soy模板无法编译为JS，配置表单无法渲染

1. 检查Soy文件路径与命名规范 #

• 确保Soy文件放置在src/main/resources/templates目录下，文件名必须以.soy结尾（如externalapi-config.soy）
• 验证Soy文件的命名空间与插件key匹配，示例：

  namespace com.yourcompany.bitbucket.hooks.externalapi.config;
  

  避免命名空间冲突导致编译忽略

2. 验证WRM插件配置 #

在pom.xml中确认WRM插件已正确配置Soy编译规则，且绑定到构建生命周期：

<plugin>
    <groupId>com.atlassian.webresource</groupId>
    <artifactId>atlassian-webresource-maven-plugin</artifactId>
    <version>4.4.4-bitbucket1</version>
    <executions>
        <execution>
            <id>wrm-build</id>
            <phase>process-resources</phase>
            <goals>
                <goal>build</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <resources>
            <resource>
                <directory>${project.basedir}/src/main/resources</directory>
                <includes>
                    <include>**/*.soy</include>
                </includes>
            </resource>
        </resources>
    </configuration>
</plugin>

• 确认WRM版本与Bitbucket DC 8.18兼容，避免版本不匹配导致编译跳过

3. 确认插件配置表单的声明正确性 #

在atlassian-plugin.xml中检查pre-receive hook的配置表单是否关联正确的web资源：

<receive-hook key="external-api-branch-hook" name="External API Branch Hook" class="com.yourcompany.hooks.ExternalApiBranchHook">
    <description>Validates branches against external API</description>
    <configuration-form>
        <web-resource key="externalapi-config-form"/>
    </configuration-form>
</receive-hook>

<web-resource key="externalapi-config-form" name="External API Config Form">
    <dependency>com.atlassian.bitbucket.server.bitbucket-web-api:bitbucket-soy</dependency>
    <resource type="download" name="externalapi-config.soy.js" location="/templates/externalapi-config.soy.js"/>
    <context>bitbucket.admin.hooks</context>
</web-resource>

• 必须依赖bitbucket-soy，这是Bitbucket渲染Soy模板的核心依赖

4. 排查Maven构建生命周期绑定 #

• 执行atlas-mvn clean package -X，重点查看process-resources阶段日志，确认WRM插件是否被触发执行
• 检查pom.xml中是否有其他插件（如资源过滤插件）覆盖了process-resources阶段，导致WRM编译被跳过

5. 手动触发Soy编译调试 #

• 直接执行WRM编译命令，强制触发Soy文件编译：

  atlas-mvn com.atlassian.webresource:atlassian-webresource-maven-plugin:build
  

• 检查编译产物是否生成在target/classes/templates目录下；若生成但未打包到JAR，需在pom.xml中添加资源配置：

  <resources>
      <resource>
          <directory>target/classes</directory>
          <includes>
              <include>**/*.soy.js</include>
          </includes>
      </resource>
  </resources>
  

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