{"record":{"id":"716067ea79677b83","repo":"wmjordan/PDFPatcher","slug":"n","errorCode":null,"errorMessage":"无法加载字体：{n}","messagePattern":"无法加载字体：(.+?)","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"App/Processor/ContentProcessors/ReplaceFontProcessor.cs","lineNumber":357,"sourceCode":"\t\t\t\t\t\t\t\tFontRef = context.Pdf.AddPdfObject(new PdfDictionary()),\r\n\t\t\t\t\t\t\t\tDescendantFontRef = context.Pdf.AddPdfObject(new PdfArray()),\r\n\t\t\t\t\t\t\t\tVertical = v,\r\n\t\t\t\t\t\t\t};\r\n\t\t\t\t\t\t\tvar fd = f.Locate<PdfDictionary>(PdfName.DESCENDANTFONTS, 0, PdfName.FONTDESCRIPTOR);\r\n\t\t\t\t\t\t\tif (fd != null) {\r\n\t\t\t\t\t\t\t\tvar num = fd.GetAsNumber(PdfName.ITALICANGLE)?.DoubleValue ?? 0d;\r\n\t\t\t\t\t\t\t\tif (num != 0) {\r\n\t\t\t\t\t\t\t\t\tnf.ItalicAngle = num;\r\n\t\t\t\t\t\t\t\t}\r\n\t\t\t\t\t\t\t}\r\n\t\t\t\t\t\t\tif (fs != null) {\r\n\t\t\t\t\t\t\t\tSetupFontSubstitutionMaps(nf, fs);\r\n\t\t\t\t\t\t\t}\r\n\t\t\t\t\t\t\tif (sn == null && p != -1 && nf.Font.BaseFont == null) {\r\n\t\t\t\t\t\t\t\tnf.Font = _fontFactory.GetFont(__AlternativeFonts[p], v ? BaseFont.IDENTITY_V : BaseFont.IDENTITY_H);\r\n\t\t\t\t\t\t\t}\r\n\t\t\t\t\t\t\tif (nf.Font.BaseFont == null) {\r\n\t\t\t\t\t\t\t\tthrow new FileNotFoundException(\"无法加载字体：\" + n);\r\n\t\t\t\t\t\t\t}\r\n\t\t\t\t\t\t\t_newFonts.Add(new FontId(n, v), nf);\r\n\t\t\t\t\t\t}\r\n\t\t\t\t\t\tcatch (Exception) {\r\n\t\t\t\t\t\t\tTracker.TraceMessage(Tracker.Category.Error, \"无法加载字体\");\r\n\t\t\t\t\t\t\tthrow;\r\n\t\t\t\t\t\t}\r\n\t\t\t\t\t}\r\n\t\t\t\t\tr[item.Key] = nf.FontRef;\r\n\t\t\t\t\tif (_fontInfoMap.ContainsKey(fr.Number) == false) {\r\n\t\t\t\t\t\tvar fi = new FontInfo(f, fr.Number);\r\n\t\t\t\t\t\t_fontInfoMap.Add(fr.Number, fi);\r\n\t\t\t\t\t\ttry {\r\n\t\t\t\t\t\t\tReadSingleByteFontWidths(f, fi, nf);\r\n\t\t\t\t\t\t\tReadCidFontWidths(f, fi, nf);\r\n\t\t\t\t\t\t}\r\n\t\t\t\t\t\tcatch (NullReferenceException) {\r\n\t\t\t\t\t\t\tTracker.TraceMessage(Tracker.Category.ImportantMessage, $\"字体“{n}”的 CID 宽度表错误。\");\r","sourceCodeStart":339,"sourceCodeEnd":375,"githubUrl":"https://github.com/wmjordan/PDFPatcher/blob/4782bbd9ada850b56258f29999b7a1c9076c9b1b/App/Processor/ContentProcessors/ReplaceFontProcessor.cs#L339-L375","documentation":"ReplaceFontProcessor.LoadFonts throws FileNotFoundException when, after attempting to load a substitute font by name (and falling back through __AlternativeFonts), the iTextSharp BaseFont is still null — meaning the font file could not be located or opened. The exception message names the offending font. A catch block logs '无法加载字体' (cannot load font) and rethrows.","triggerScenarios":"Running font replacement on a PDF whose embedded/legacy font name is not installed on the system and is not in the __AlternativeFonts fallback list. The code calls _fontFactory.GetFont(name, encoding) which returns a Font with BaseFont==null when the TTF/OTF cannot be found, and the guard at line 356-358 converts that into FileNotFoundException.","commonSituations":"Processing a PDF referencing a CJK or legacy font (e.g. a subset-prefixed name) that isn't installed on the machine; missing font files in the application's font directory; a font name with encoding issues (vertical '-V' variant) that doesn't match an installed file; deployed environment lacking the required font assets.","solutions":["Install the missing font (named in the exception message) on the system or in the app's font folder.","Configure a font substitution mapping (FontSubstitution) so the missing font maps to an available one.","Ensure the __AlternativeFonts fallback list includes a suitable replacement and that those files exist.","Verify the font file path and that the process has read permissions.","If embedding legacy CJK fonts, confirm the legacy font files ship with the application."],"exampleFix":"// before\nnf.Font = _fontFactory.GetFont(sf ?? n, v ? BaseFont.IDENTITY_V : BaseFont.IDENTITY_H);\nif (nf.Font.BaseFont == null)\n  throw new FileNotFoundException(\"无法加载字体：\" + n);\n\n// after\nnf.Font = _fontFactory.GetFont(sf ?? n, v ? BaseFont.IDENTITY_V : BaseFont.IDENTITY_H)\n  ?? _fontFactory.GetFont(__DefaultFallbackFont, v ? BaseFont.IDENTITY_V : BaseFont.IDENTITY_H);\nif (nf.Font.BaseFont == null) {\n  Tracker.TraceMessage(Tracker.Category.Warning, $\"字体不可用，跳过：{n}\");\n  goto BYPASSFONT;\n}","handlingStrategy":"try-catch","validationCode":"if (!FontUtility.InstalledFonts.Any(f => f.DisplayName == fontName)\n    && !File.Exists(Path.Combine(fontDir, fontName + \".ttf\")))\n    return; // skip replacement","typeGuard":"static bool IsFontAvailable(string name) =>\n    FontUtility.InstalledFonts.Any(f => f.DisplayName == name);","tryCatchPattern":"try { LoadFonts(context, fonts); }\ncatch (FileNotFoundException ex) {\n  Tracker.TraceMessage(Tracker.Category.Error, $\"缺少字体，跳过：{ex.Message}\");\n}","preventionTips":["Install or bundle all fonts referenced by the PDFs you process.","Configure FontSubstitution mappings for known-missing fonts.","Ensure __AlternativeFonts fallback files ship with the app.","Run on an environment with the required CJK font packs."],"tags":["pdf","font","file-not-found","configuration","environment"],"backgroundTag":null,"analyzedSha":"4782bbd9ada850b56258f29999b7a1c9076c9b1b","analyzedAt":"2026-08-13T17:44:50.812Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}