文章目录一、它演示什么二、怎么用三、一屏总览四、关键接口五、容易踩的坑六、错误排查与日志解读八、常见问题 FAQ1. 文件打不开2. 空文件与无法读取的区别3. 差异表只显示前 200 条4. 配置文件缺失导致窗口尺寸异常一、它演示什么面向固件与镜像发布的纯离线工具A / B 两个文件槽选中后立刻给出大小与 MD5 / SHA1 / SHA256 / SHA512 / CRC32「比对」先比大小再比 SHA256「找差异」逐字节比报告可复制 / 导出文件还能拖进窗口按 A、B 顺序落槽。补的能力面是只读摘要计算不必整读进内存 逐字节差异定位 报告导出 拖放。工控里就是 —— 核对两个固件 / 镜像是不是同一个、不一样差在哪。二、怎么用点两个「选择文件…」把文件填进 A、B或直接把文件拖进窗口按 A、B 顺序落槽。选中后立刻在日志term_log里看到大小与五种摘要。点「开始比对」给出「一致 / 不一致 / 无法比对」结论与状态灯绿一致 / 红不一致 / 灭无法比对。点「找差异」两文件都读得动且 ≤ 4 MB 时逐字节比差异全部计数、表格tbl_diff只列前 200 条。点「复制报告」进剪贴板 / 「导出报告」写成 .txt点「清空」清掉两槽、结论、差异表与日志。命令行filecheck.exe自动找同名.cgui、filecheck.exe xxx.cgui、--selftest。三、一屏总览控件 id类型干什么edt_a_path/edt_b_pathedit文件 A / B 路径btn_a_pick/btn_b_pickbutton选择文件led_verdict/lab_verdictled / label结论灯与结论文字btn_cmpbutton比大小与 SHA256btn_diffbutton逐字节找差异btn_copy/btn_exportbutton复制报告 / 导出报告btn_clearbutton清空term_logterminal大小 / 五种摘要 / 结论tbl_difftable偏移 / A 的字节 / B 的字节sb_mainstatusbar状态 / A、B 槽四、关键接口cg_file_size取大小cg_hash_file算 MD5 / SHA1 / SHA256 / SHA512cg_crc32_file算 CRC32cg_file_read_bytes只在逐字节比对时读cg_clip_set_text复制报告cg_file_write导出报告cg_ini_read/cg_ini_write记窗口尺寸与上次的 A / B 路径cg_app_data_dir定位配置文件。五、容易踩的坑大文件比对超限现象是点「找差异」后表格tbl_diff一直空白、结论灯熄灭日志出现size over limit/too large。原因是文件超过 4 MB 上限逐字节比对被跳过。解决看term_log里的size N确认大小超限时改用「开始比对」只比大小与 SHA256或把文件拆小后再比。拖放路径含中文现象是拖进窗口后edt_a_path/edt_b_path显示乱码或路径被截断日志出现path decode failed/invalid path。原因是拖放事件对非 ASCII 路径处理不当。解决改用「选择文件…」按钮落槽或把文件复制到纯英文路径下再拖放。配置文件损坏现象是窗口尺寸异常、上次的 A / B 路径丢失日志出现config parse error/bad ini。原因是.cgui被外部编辑器改坏或写入中断。解决删除cg_app_data_dir下的.cgui工具会自动重建默认配置重新选择文件后cg_ini_write会再次落盘。空文件与打不开必须分清现象是空文件能比大小、能算摘要打不开的文件连摘要都算不出。原因是两者在cg_file_size/cg_hash_file的返回路径不同。解决先看term_log里size 0判定为空文件出现open failed/read error才是打不开别把「无法比对」误判成「文件为空」。全程不 malloc/free现象是接入自有内存管理后偶发崩溃日志无明确关键字。原因是绕开框架堆串直接malloc与cg_free不匹配。解决统一用框架堆串释放一律走cg_free不要混用。六、错误排查与日志解读八、常见问题 FAQQ1大文件比对超限如何处理文件超过 4 MB 时逐字节比对会被跳过日志出现size over limit/too large。改用「开始比对」只比大小与 SHA256或把文件拆小后再比。详见「五、容易踩的坑 · 大文件比对超限」。Q2拖放中文路径乱码怎么办拖放事件对非 ASCII 路径处理不当日志出现path decode failed/invalid path。改用「选择文件…」按钮落槽或把文件复制到纯英文路径下再拖放。详见「五、容易踩的坑 · 拖放路径含中文」。Q3配置文件损坏如何恢复.cgui被外部编辑器改坏或写入中断时日志出现config parse error/bad ini。删除cg_app_data_dir下的.cgui工具会自动重建默认配置重新选择文件后cg_ini_write会再次落盘。详见「五、容易踩的坑 · 配置文件损坏」。Q4空文件与打不开如何区分空文件能比大小、能算摘要size 0打不开的文件连摘要都算不出open failed/read error。别把「无法比对」误判成「文件为空」。详见「六、错误排查与日志解读 · 2. 空文件与无法读取的区别」。Q5差异表只显示 200 条如何查看完整结果tbl_diff只列前 200 条但term_log末尾的diff total N是全部差异数。若 N 200点「导出报告」把完整差异写入 .txt 再查看。详见「六、错误排查与日志解读 · 3. 差异表只显示前 200 条」。按现象分类对照term_log里的关键字快速定位问题1. 文件打不开现象点「开始比对」或「找差异」后结论灯熄灭日志出现open failed/cannot open/access denied。排查步骤确认路径里没有中文或空格导致的转义问题必要时改用拖放落槽。检查文件是否被占用如正在被写入的固件包。看sb_main状态栏是否提示「无法读取」。日志关键字open failed、cannot open、access denied。2. 空文件与无法读取的区别现象空文件能比大小、能算摘要无法读取的文件连摘要都算不出。排查步骤空文件size 0五种摘要均为空串结论为「一致 / 不一致」按大小判定。无法读取日志出现read error/io error结论灯熄灭显示「无法比对」。日志关键字size 0空文件、read error/io error无法读取。3. 差异表只显示前 200 条现象tbl_diff只列前 200 条但差异总数可能更多。排查步骤看term_log末尾的diff total NN 即全部差异数。若 N 200点「导出报告」把完整差异写入 .txt再在文件里查看全部条目。日志关键字diff total 。4. 配置文件缺失导致窗口尺寸异常现象窗口回到默认尺寸A / B 路径为空。排查步骤确认cg_app_data_dir指向的目录下是否存在.cgui配置文件。缺失时工具自动按默认尺寸重建窗口属正常行为无需报错。若想恢复上次路径重新选择文件后工具会再次写入配置。日志关键字config not found、use default。逐字节比对只在两个文件都读得动且 ≤ 4 MB 时才做超限改为比摘要、不硬读进内存。差异全部计数但表格只列前 200 条。空文件与打不开必须分清前者能比大小后者连摘要都算不出。全程不 malloc/free只用框架堆串配cg_free。