Freemarker模板构建阶段出现loadJSON函数空值/缺失错误，本地IDE运行正常的问题求助

我来帮你拆解下这个「本地正常、构建报错」的Freemarker问题——这种环境差异导致的问题，大概率和路径定位、资源加载方式、构建环境权限/依赖有关，咱们一步步排查：

核心问题定位 #

报错提示loadJSON求值为null或缺失，结合你的代码来看，可能是这几个环节出了问题：

• 构建环境中找不到目标JSON文件，导致函数执行抛出异常，最终Freemarker无法识别该函数
• 函数注册时机不对，构建流程中loadJSON没被正确注入到Freemarker模型里
• 构建环境缺少JSON解析依赖，导致函数执行失败

具体排查与解决步骤 #

1. 优先解决「文件路径不兼容」问题 #

本地IDE的工作目录和构建流程（比如CI流水线、Maven/Gradle打包）的工作目录大概率不一样，直接用相对路径找文件很容易踩坑。

• 调试方法：在loadJSON方法开头加一行日志，打印当前工作目录：

  LOGGER.info("Current working dir: " + System.getProperty("user.dir"));
  

  对比本地和构建环境的输出，就能看出路径差异。
• 解决方案：改用类路径加载资源（把JSON文件放到src/main/resources下），避免依赖文件系统路径：
  修改loadJSON方法：

  private String loadJSON(String resourcePath) {
      JSONParser parser = new JSONParser();
      // 用类路径流读取，兼容打包后的环境
      try (InputStream is = getClass().getResourceAsStream(resourcePath)) {
          if (is == null) {
              String errMsg = "JSON resource not found: " + resourcePath;
              LOGGER.warning(errMsg);
              throw new RuntimeException(errMsg);
          }
          return parser.parse(new InputStreamReader(is)).toString();
      } catch (Exception e) {
          String errMsg = "Failed to parse JSON: " + e.getLocalizedMessage();
          LOGGER.warning(errMsg);
          throw new RuntimeException(errMsg, e); // 不要吞异常，抛出明确错误
      }
  }
  

  模板里的路径改成类路径格式：

  <#assign keywordsJSON = loadJSON('/random.json')> <!-- 对应resources下的random.json -->
  

2. 检查「函数注册时机」 #

本地IDE中addUtilityFunctions可能在模板渲染前正确执行，但构建流程中可能因为初始化顺序问题，导致loadJSON没被注入到模型里。

• 调试方法：在addUtilityFunctions里加日志确认：

  protected void addUtilityFunctions(String baseURL, Map<String, Object> model) { 
      model.put("loadJSON", parseJSON()); 
      LOGGER.info("loadJSON function added to model? " + model.containsKey("loadJSON"));
  }
  

• 解决方案：确保addUtilityFunctions在调用Template.process(model, writer)之前执行，且模型对象被正确传递给Freemarker渲染逻辑。

3. 排查「构建环境依赖/权限」 #

• 依赖缺失：本地IDE有JSON解析依赖（比如org.json），但构建脚本里可能把依赖scope设成了provided，导致打包后缺少依赖。检查pom.xml/gradle配置，确保JSON依赖的scope是compile或runtime：

  <!-- Maven示例 -->
  <dependency>
      <groupId>org.json</groupId>
      <artifactId>json</artifactId>
      <version>20240303</version>
  </dependency>
  

• 文件权限：构建服务器的运行用户可能没有读取JSON文件的权限，导致FileReader抛异常。可以在构建脚本中添加权限设置（比如Linux下chmod 644 path/to/random.json）。

4. 不要吞异常！ #

你的代码中catch块只打了warning就返回字符串，但Freemarker在函数执行抛出异常时，可能会判定该函数无效。建议在catch块重新抛出RuntimeException，这样构建日志会输出完整的异常栈，更容易定位问题。

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