{"record":{"id":"b8da192dda5af69f","repo":"YunaiV/ruoyi-vue-pro","slug":"iputils","errorCode":null,"errorMessage":"IPUtils 初始化失败","messagePattern":"IPUtils 初始化失败","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"yudao-framework/yudao-spring-boot-starter-biz-ip/src/main/java/cn/iocoder/yudao/framework/ip/core/utils/IPUtils.java","lineNumber":40,"sourceCode":"     * IP 查询器，启动加载到内存中\n     */\n    private static Searcher SEARCHER;\n\n    static {\n        init();\n    }\n\n    /**\n     * 初始化\n     */\n    private static void init() {\n        try {\n            long now = System.currentTimeMillis();\n            byte[] bytes = ResourceUtil.readBytes(\"ip2region.xdb\");\n            SEARCHER = Searcher.newWithBuffer(bytes);\n            log.info(\"启动加载 IPUtils 成功，耗时 ({}) 毫秒\", System.currentTimeMillis() - now);\n        } catch (Exception e) {\n            throw new RuntimeException(\"IPUtils 初始化失败\", e);\n        }\n    }\n\n    /**\n     * 查询 IP 对应的地区编号\n     *\n     * @param ip IP 地址，格式为 127.0.0.1\n     * @return 地区id\n     */\n    @SneakyThrows\n    public static Integer getAreaId(String ip) {\n        return Integer.parseInt(SEARCHER.search(ip.trim()));\n    }\n\n    /**\n     * 查询 IP 对应的地区编号\n     *\n     * @param ip IP 地址的时间戳，格式参考{@link Searcher#checkIP(String)} 的返回","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/YunaiV/ruoyi-vue-pro/blob/0418084e222612af2fc1141f566af454f9236ab1/yudao-framework/yudao-spring-boot-starter-biz-ip/src/main/java/cn/iocoder/yudao/framework/ip/core/utils/IPUtils.java#L22-L58","documentation":"IPUtils statically loads the ip2region.xdb binary into a Searcher. If ResourceUtil.readBytes('ip2region.xdb') fails (resource missing) or Searcher.newWithBuffer throws (corrupt/unsupported xdb format), init() wraps the cause as RuntimeException('IPUtils 初始化失败'). The SEARCHER field stays null, so any later getAreaId would NPE, hence fail-fast at class load.","triggerScenarios":"ip2region.xdb is not packaged into the classpath (maven resource filtering/shading dropped it); the xdb file is corrupt or truncated; an incompatible ip2region version that rejects the buffer format.","commonSituations":"Shaded jar missing the .xdb; resource path case mismatch on case-sensitive FS; building on a platform that mangles the binary during filtering.","solutions":["Confirm ip2region.xdb is present in the classpath (inspect the built jar).","Exclude the .xdb from Maven resource filtering (binary filtering corrupts it): add <nonFilteredFileExtensions>xdb</nonFilteredFileExtensions>.","Re-download a known-good ip2region.xdb if it is corrupt.","Pin a compatible ip2region SDK version matching the xdb format."],"exampleFix":"// before: resource filtering corrupts the binary\n// pom.xml (spring-boot): resources with filtering on all\n// after: exclude binary from filtering\n<plugin>\n  <artifactId>maven-resources-plugin</artifactId>\n  <configuration>\n    <nonFilteredFileExtensions>xdb</nonFilteredFileExtensions>\n  </configuration>\n</plugin>","handlingStrategy":"try-catch","validationCode":"if (getClass().getClassLoader().getResource(\"ip2region.xdb\") == null)\n    throw new IllegalStateException(\"ip2region.xdb missing from classpath\");","typeGuard":"null","tryCatchPattern":"try { IPUtils.getAreaId(ip); }\ncatch (RuntimeException e) { if (e.getMessage().contains(\"IPUtils\")) { /* return unknown region */ } throw e; }","preventionTips":["Add xdb to nonFilteredFileExtensions in maven-resources-plugin","Verify the .xdb is in the built jar","Pin a compatible ip2region SDK version"],"tags":["yudao","ip","ip2region","startup","resource-loading"],"backgroundTag":null,"analyzedSha":"0418084e222612af2fc1141f566af454f9236ab1","analyzedAt":"2026-08-14T00:56:18.412Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}