编译报错“Cannot find module XXX or its corresponding type declarations”
===================================================================

*   **场景一：**
    
    **问题现象**
    
    Stage模板工程编译引用native文件(.so) 提示“Cannot find module XXX or its corresponding type declarations.”。
    
    **解决措施**
    
    当前Stage工程在编译构建阶段新增对native文件（.so）导出符号的语法校验。如果现有工程引用了没有对应声明文件（.d.ts）的native文件（.so），语法校验工具会报错，提示找不到对应的声明文件。
    
    如果出现类似问题，尝试以下解决方法：
    
    1.  在对应cpp目录下新建types/libxxx目录，并在该目录下新增index.d.ts用于声明native文件的类型符号；新增oh-package.json5配置文件用于校验工具的模块查询。
        
        ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/12/v3/hllumyUxRw6L8ppGh4qkag/zh-cn_image_0000002229604373.png?HW-CC-KV=V1&HW-CC-Date=20260612T074806Z&HW-CC-Expire=86400&HW-CC-Sign=13AEAFA173AB6E8A811321C22FF1E3293D88939F45540773D51F3D1957AEAEA7)
        
        ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/3a/v3/lW2jzYOxSWaxpkBqm0fs7Q/zh-cn_image_0000002194158980.png?HW-CC-KV=V1&HW-CC-Date=20260612T074806Z&HW-CC-Expire=86400&HW-CC-Sign=F3F71B652823A6D3A8FAA7EC39DB256B291CC1818BA390181768377A626341FE)
        
    2.  在native文件引用的模块内的oh-package.json5中添加native文件的本地依赖，并根据DevEco Studio提示点击\*\*Sync Now\*\*同步工程，下图以entry模块引用native文件为例。
        
        ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/32/v3/ILTR5EXhSIqyBfJYw9zCLA/zh-cn_image_0000002194318572.png?HW-CC-KV=V1&HW-CC-Date=20260612T074806Z&HW-CC-Expire=86400&HW-CC-Sign=EF1D1F8271BDD00F7CB0358B14D916F06CC11EE22CA214998054854F886CE405)
        

*   **场景二：**
    
    **问题现象**
    
    API 11 Stage模板工程编译失败，提示“Cannot find module '@kit.xxx' or its corresponding type declarations”。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/cf/v3/q0My6S1cSbKQaz3x7SgI-Q/zh-cn_image_0000002229758849.png?HW-CC-KV=V1&HW-CC-Date=20260612T074806Z&HW-CC-Expire=86400&HW-CC-Sign=C4F228D3B2B4B957A6A67DF0854C4D675450CE18FAC7B92C89B9E95CC87759EE)
    
    **问题原因**
    
    出现该问题的原因是使用DevEco Studio NEXT Developer Preview1及之后版本。新创建的API 11 Stage模型的模板文件中，import方式改为import xxx from '@kit.xxx'。若SDK使用的是HarmonyOS NEXT Developer Preview1之前的版本，将会出现编译报错，因为旧的SDK不支持此类方式导入。
    
    **解决措施**
    
    如果出现类似问题，需要对SDK进行更新或更新DevEco Studio。
    
    *   如果使用的是DevEco Studio NEXT Developer Preview1至HarmonyOS NEXT Developer Beta1（5.0.3.300）之间的版本，在菜单栏点击**Tool > SDK Manager**，将SDK更新至HarmonyOS NEXT Developer Preview1及以上版本后，重新进行编译。
    *   如果使用的是HarmonyOS NEXT Developer Beta1（5.0.3.300）及以上的版本，SDK随DevEco Studio软件包安装，无需单独下载，请在[下载中心](https://developer.huawei.com/consumer/cn/download/)下载并使用新版本DevEco Studio。
*   **场景三：**
    
    **问题现象**
    
    引用第三方包，构建失败，提示“Cannot find module 'xxx' or its corresponding type declarations”。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/13/v3/G32_ghXqRDmiEePxKev56g/zh-cn_image_0000002229758853.png?HW-CC-KV=V1&HW-CC-Date=20260612T074806Z&HW-CC-Expire=86400&HW-CC-Sign=34A4516C6D0AD0DBB7F28613353923EFA9E85251819A497EED0985C78232D7A2)
    
    **解决措施**
    
    进入模块级或工程级的oh-package.json5文件，检查第三方包是否已安装。若未安装，执行ohpm install安装。若已安装，检查“main”字段是否配置正确。若未配置或配置错误，需配置为正确的入口文件。
    
*   **场景四：**
    
    **问题现象**
    
    包路径被混淆，代码中又是在引用包路径后面拼接了路径，导致模块引用不到而报错。
    
    例如：
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/a9/v3/V6XT28AATCSPdRA9IkfQ_g/zh-cn_image_0000002194158984.png?HW-CC-KV=V1&HW-CC-Date=20260612T074806Z&HW-CC-Expire=86400&HW-CC-Sign=68AE035AA12B64BA27E4831AF4997FD41A97EA8ACC7574FF0D6220EBADAA05E5)
    
    代码中这样引用
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/7c/v3/un_zipILQpSHGHLxpNEn1g/zh-cn_image_0000002229758861.png?HW-CC-KV=V1&HW-CC-Date=20260612T074806Z&HW-CC-Expire=86400&HW-CC-Sign=4C37B2215FCB32A2E87E926E561087D613A83CBB3DC7317B52ED841EC6901311)这样引用会找不到模块，导致报错。
    
    **解决措施**
    
    修改引用方式，采用推荐的方式。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/92/v3/P4WkBBuPTFSrjE-pT5cdcQ/zh-cn_image_0000002194158972.png?HW-CC-KV=V1&HW-CC-Date=20260612T074806Z&HW-CC-Expire=86400&HW-CC-Sign=DCEFDFF40AD3E697EE8D1BB69C40CC3CBF6761D6DC80F50B33CDBAF7C6E7F6E2)
    
*   **场景五：**
    
    **问题现象**
    
    被引用模块oh-package.json5配置有误，执行了ohpm install 并且成功地安装了依赖，但是还报错模块找不到。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/37/v3/zcHLDWDiTzWYGBgre3J5Lw/zh-cn_image_0000002194158976.png?HW-CC-KV=V1&HW-CC-Date=20260612T074806Z&HW-CC-Expire=86400&HW-CC-Sign=FFAE29BEBDB43247D719CFDC492D924E09BA273E936865F16998DA6A3D20BDDB)
    
    被引用模块的 oh-package.json5 中配置了错误的types字段。
    
    该字段优先于main字段。 如果 types 字段配置的不存在，就会报错模块找不到。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/eb/v3/UzKeXUIRRWO1gC0uDVH8uQ/zh-cn_image_0000002229604353.png?HW-CC-KV=V1&HW-CC-Date=20260612T074806Z&HW-CC-Expire=86400&HW-CC-Sign=A1BB1CABA6DC2E11072743BECFB3BAF75636066982D05C1F85D9A8AFA3A7D564)
    
    **解决措施**
    
    如果该包中没有d.ets声明，可以删除这个字段。配置错误或不存在会导致报错。
    
*   **场景六：**
    
    **问题现象**
    
    oh-package.json5中dependencies中引入模块的名称和实际使用时import的不一致。
    
    在代码中“import”时，应使用大写的“HAR”而不是“dependencies”里配置的“har”。务必保持完全一致，否则在Linux系统中会报错，提示模块找不到。
    
    **解决措施**
    
    引入和使用改成一致。
    
*   **场景七：**
    
    **问题现象**
    
    引用模块的oh-package.json5中main字段值和实际的文件名称大小写不一致。
    
    **解决措施**
    
    将main字段和实际文件名称大小写改为一致。
    
*   **场景八**：
    
    **问题现象**
    
    Stage模板工程编译构建失败，提示“Cannot find module '@bundle:rollup\_plugin\_ignore\_empty\_module\_placeholder' or its corresponding type declarations”。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c7/v3/dgZzLIIWRfmCFPiECX0Sfw/zh-cn_image_0000002229758841.png?HW-CC-KV=V1&HW-CC-Date=20260612T074806Z&HW-CC-Expire=86400&HW-CC-Sign=73C1595BDFDEFCD7438557E8B8792783DC60773E08143CD7950D73E836ADA73E)
    
    **解决措施**
    
    该问题源于工程引用了无对应实现文件的.d.ts声明文件。
    
    1.  在build目录搜索\`rollup\_plugin\_ignore\_empty\_module\_placeholder\`定位问题模块。
        
        ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/83/v3/Bmf-7VCYR-akP-WkuZI2iA/zh-cn_image_0000002194158956.png?HW-CC-KV=V1&HW-CC-Date=20260612T074806Z&HW-CC-Expire=86400&HW-CC-Sign=69CF5B28AC0DFE6417B80BF40AA21F89CEA13D7B30715A6954A02B3F69AF3D98)
        
        在输入栏中输入“rollup\_plugin\_ignore\_empty\_module\_placeholder”，找到问题模块的中间文件。
        
        ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/2a/v3/ZcgkrA_qS46gDB_wMG9Lpw/zh-cn_image_0000002194158964.png?HW-CC-KV=V1&HW-CC-Date=20260612T074806Z&HW-CC-Expire=86400&HW-CC-Sign=9E34F1F1BA21CEEA9C5ABF5797057220F8098E9AAAFD53CCDEB1FE7B667F0401)
        
    
    2.  在引用类型文件中通过添加type显式声明符号类型。
        
        ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/a8/v3/f0QowAzaSQCE1--yIXlqdw/zh-cn_image_0000002229758865.png?HW-CC-KV=V1&HW-CC-Date=20260612T074806Z&HW-CC-Expire=86400&HW-CC-Sign=9511D1CC0C7FF79DFF333E539DE49EDE6B3219744E0AAE858B93D5C4979A5E38)
        
    
    3.  同时排查是否从d.ts/d.ets中引用值类型符号。禁止在声明文件中声明值变量。
        
        ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/5d/v3/mJBuzMmXSamJKRqARIWZtg/zh-cn_image_0000002194158968.png?HW-CC-KV=V1&HW-CC-Date=20260612T074806Z&HW-CC-Expire=86400&HW-CC-Sign=DEB64D1CCCE592ACE636ECA12B938B619CE2AC26D86557AE6D4B5824CE503407)