Why do Chinese characters turn into boxes on a client's phone when the PDF looks fine on my computer: missing font embedding or an unsupported reader?

Conclusion: When Chinese text looks fine in a PDF on your own computer but appears as boxes on a client's phone, the common cause is not that the server lacks fonts. It is that one of three links is broken: the font file, font family name matching, or glyph embedding. Based on typical 2026 delivery experience, do not reinstall fonts first. Check in the four-layer order of file → registration → matching → embedding; in most cases you can identify the specific layer within half an hour to half a day.

1. Installing a font does not mean the font is embedded in the PDF

When a server generates a PDF, fonts involve at least three stages: the font file exists in the runtime environment; the rendering engine can find it by the family name written in the template; and the glyphs used are embedded as a subset into the PDF during generation. Copying ttf/otf files into /usr/share/fonts solves only the first stage. If the PDF opens normally on the development machine but shows boxes for the client, the common explanation is that local fonts covered the missing characters while the exported file did not embed them.

• The file exists, but the font cache was not refreshed; fc-list cannot list the family, so the engine treats it as absent;
• The file name looks like a Chinese font, but the internal family name is written differently, so “Songti” and “Heiti” in the template do not match;
• The name matches, but only a subset is embedded; dynamically inserted rare characters and full-width punctuation are not in the subset;
• It is installed on the host machine but not in the container image, so the issue recurs after changing machines or redeploying.

2. Four-layer diagnosis: from font file to embedding result

PDF generation is a one-way chain: file → system registration → engine matching → embedded output. Reverse-engineering from the finished PDF easily leads to wrong guesses; checking in a fixed order is faster.

1. Check the file: enter the runtime environment (for containerized deployments, enter the container), confirm the target font file exists, and note its path;
2. Check registration: run fc-list. The system recognizes the font only if the corresponding family is listed. If not, refresh the cache first, then check the path and permissions;
3. Check matching: write the exact family name from fc-list output into the template. When the engine supports specifying the font file path directly, that is usually more reliable than writing the name;
4. Check embedding: use pdffonts or the reader's document properties to see whether the font is marked as embedded. If the first three layers pass and this layer fails, the generation parameters have turned off embedding.

Suggested acceptance criterion: open the exported PDF on a clean computer and phone without extra Chinese fonts installed, and confirm that Chinese characters, punctuation, and symbols display correctly. Do not write only “it opens fine on my side.”

3. HTML-to-PDF vs. direct template rendering: the difference is not just development effort

The two approaches depend differently on the system font directory, and they differ in whether the issue recurs after changing environments. Below are typical experience ranges; actual numbers vary with template complexity and team familiarity.

• HTML-to-PDF: existing page styles can be reused; the first version commonly takes 0.5–2 person-days. It depends on the runtime environment's font directory, the image size commonly increases by tens to one or two hundred MB, and pagination, repeating table headers across pages, and footer page numbers need repeated tuning.
• Direct template rendering: pagination, tables, page numbers, and watermarks are more controllable; fonts are loaded as file streams and do not depend on the system font directory. The cost is that layout must be coded; it commonly takes 3–10 person-days, and changing styles means changing code.
• Hybrid approach: use direct template rendering for fixed-layout contracts, invoices, and statements; use HTML-to-PDF for explanatory documents with variable page counts; both share the same font files.

In terms of selection, if the layout depends heavily on design mockups, the page count is variable, and you need to reproduce the web look, lean toward the former; if the layout is fixed, fields are regular, and you generate thousands of copies in batches, lean toward the latter. For occasional one- or two-page confirmation forms, forcing direct template rendering easily becomes over-engineering.

4. Delivery case: a minimal intranet image and two fonts

We have encountered a client intranet server using a minimal image, with no external network and no way to install a package manager. The client provided only one font license file, while the contract template used one font for the title and another for the body. In the first version, we copied the available font into the image; the title rendered, but the body still showed boxes. After temporarily unifying the body family to an available font, all Chinese displayed, but the client required the title to keep its original font. Finally, we packaged both font files into the image and checked the template font names item by item. There were two rounds of back-and-forth rework, and the overall cycle was two or three days longer than planned. This type of rework is not rare within the experience range; the typical range is half a day to three days, depending on font licensing and the number of font types in the template.

Before acceptance, check in advance: fonts are installed only on the host machine, not in the container; only whole paragraphs of Chinese are tested, without testing rare characters, full-width punctuation, currency symbols, or Chinese title marks; files are packaged before font copyright is confirmed; embedding the full font makes a several-hundred-page document grow from a few MB to tens of MB; the PDF is only viewed in a desktop reader and not opened in the phone's built-in reader.

5. When this applies and when it does not

This order applies to server-side generation of Chinese PDFs such as contracts, invoices, reports, certificates, and statements. It also applies to missing characters caused by inconsistent fonts across test, staging, and production environments.

• Applies: server-side batch generation, archival needs, and PDFs sent directly to external clients to open and view;
• Applies: containerized deployments where missing characters recur after changing machines;
• Not necessary: content contains only numbers and English, and system fonts are sufficient;
• Does not apply: the PDF is generated on the client side (browser printing, front-end library export); the troubleshooting point is the user's machine and browser;
• Does not apply: the client requires text in the PDF to be editable while retaining the original font; this involves font licensing and embedding strategy and must be agreed separately.

On boundaries, distinguish clearly: packaging fonts into the image solves display, not licensing. Copyrighted commercial fonts must be used within the client's written authorization scope. If written confirmation is unavailable, prioritize switching to a commercially usable font before discussing layout fidelity; in 2026 project compliance reviews, this point is often raised early.

Next time Chinese text appears as boxes in a PDF, first go through the four layers—file, registration, matching, embedding; most problems can be traced to a specific layer. When the layout is fixed and batch volume is high, choose a solution that does not depend on the system font directory at the start of the project; this avoids repeated troubleshooting after environment changes. Font licensing remains subject to the client's written confirmation scope.

Frequently asked questions

When a client's phone shows boxes but my own computer looks fine, should I check embedding or the font name first?

Check embedding first. Use pdffonts or document properties to see whether the font is embedded; if not, go back and check the template family name. If your own computer looks fine, it is often because local fonts covered the missing characters.

fc-list shows the font, but writing “Songti” in the template still produces boxes; how should I match the name?

Replace the colloquial name with the exact family name from fc-list output, and check inside the same container where the export process runs. A single space difference or a Chinese vs. English parenthesis can cause a mismatch.

Is one Chinese font file enough in the container image?

It depends on how many families the template uses. The experience range is to include 1–2 fonts that the business actually uses. If the title and body use different families and you include only one, the typical result is that the title renders and the body shows boxes.

Can a commercial font provided by the client be packaged into the image and sent externally?

Do not rely only on “the client provided it.” Confirm that the written authorization covers server embedding and external distribution; if it does not, switch to a commercially usable font instead of waiting for a delivery compliance review and reworking.