PDF cfdocument kosong atau berbeza antara pelayan

PDF yang dijana oleh tag <cfdocument> keluar kosong, hanya separuh, atau berbeza apabila dibuka dari dua pelayan, hampir selalu berpunca daripada empat perkara: kandungan tidak pernah dikeluarkan daripada pemboleh ubah, imej dan CSS yang tidak dapat diselesaikan kerana localurl, fon sistem yang tidak sama, dan versi enjin yang berbeza. Artikel ini menunjukkannya dengan PDF sebenar yang dijana dalam pelayan Lucee, lengkap dengan saiz fail yang diukur, supaya anda tahu bezanya antara PDF yang betul, PDF yang kosong, dan PDF yang kehilangan imej.

Apa yang berlaku bila PDF keluar kosong

PDF kosong bukan satu ralat sahaja. Ia boleh jadi PDF yang sah dari segi struktur tetapi tiada kandungan, atau halaman web yang memulangkan kod status 200 tetapi badan kosong. Kedua-duanya kelihatan sama di mata pembaca, tetapi punca dan jalan penyelesaiannya berbeza. Sebelum menyalahkan tag, semak dahulu bentuk mana yang anda hadapi.

Perkara paling mudah ialah menyemak saiz fail. PDF yang benar-benar kosong dijana daripada <cfdocument> yang badannya tiada apa-apa masih menghasilkan rangka PDF yang sah. Dalam rig ujian, rangka itu bersaiz 790 bait. PDF dengan beberapa baris teks bersaiz 1254 bait. Kalau fail anda sifar bait atau badan halaman balas kosong, masalahnya bukan pada kandungan, tetapi pada cara anda mengeluarkan PDF itu.

name lawan filename: dua cara simpan PDF

Tag <cfdocument> memberi dua jalan untuk menyimpan hasil. Atribut name menyimpan binari PDF ke dalam pemboleh ubah di dalam memori, manakala filename menulis terus ke fail pada cakera. Kedua-duanya berfungsi, tetapi pengaturcara yang memilih name perlu mengambil satu langkah tambahan untuk mengeluarkan pemboleh ubah itu, dan di sinilah kebanyakan PDF kosong bermula.

<cfdocument format="pdf" name="dok" pagetype="a4" fontembed="yes">
    <h1>Invois Ujian Lucee</h1>
    <p>Ini ialah kandungan sebenar yang dijana menjadi PDF melalui tag cfdocument.</p>
    <p>Baris kedua memastikan dokumen mempunyai badan yang boleh diukur.</p>
    <p>Baris ketiga dengan senarai: satu, dua, tiga.</p>
</cfdocument>
<cfset sasaran = expandPath("./invois.pdf")>
<cffile action="write" file="#sasaran#" output="#dok#">
<cfoutput>Saiz PDF: #len(dok)# bait</cfoutput>

Dalam ujian sebenar, blok di atas menghasilkan PDF bersaiz 1254 bait dan len(dok) memulangkan 1254, iaitu nilai yang sama. PDF itu bukan kosong. Kalau anda memilih filename, langkah cffile itu tidak perlu kerana enjin menulis fail untuk anda, dan fail PDF 1150 bait tercipta tanpa baris tambahan.

Masalah paling biasa ialah memilih name tetapi terlupa mengeluarkannya. Halaman di bawah menjana PDF ke dalam dok dan kemudian berhenti tanpa menulis atau menghantar apa-apa.

<cfdocument format="pdf" name="dok" pagetype="a4">
    <h1>PDF Ini Tidak Pernah Dikeluarkan</h1>
</cfdocument>

Halaman ini membalas kod status 200 dengan jenis kandungan text/html, tetapi badannya cuma 2 bait kosong. Tiada ralat dibaling, tiada PDF dihantar, dan pembaca melihat halaman putih. Itulah sebab PDF kosong jarang disertai mesej ralat: enjin tidak tahu anda mahu dok itu sampai ke pelayar.

localurl dan imej yang hilang

Atribut localurl ialah boolean yes atau no, bukan laluan direktori. Ini kesilapan yang kerap berlaku kerana pembangun membaca dokumentasi dan menyangka ia menerima laluan. Apabila anda menghantar rentetan laluan, Lucee membalas Can't cast String [...] to a boolean. Dengan localurl="yes", imej yang dirujuk melalui laluan relatif dibaca terus dari cakera berbanding direktori templat. Dengan nilai lalai no, imej diambil melalui HTTP, jadi laluan relatif yang menunjuk ke fail di luar webroot gagal dan imej itu dibuang secara senyap.

<cfdocument format="pdf" name="dok" pagetype="a4" localurl="yes">
    <h1>Kad Ahli</h1>
    <img src="imej/logo.png" width="120" height="120" alt="Logo">
</cfdocument>

Dalam rig ujian, PDF dengan imej yang berjaya dibenamkan bersaiz 1874 bait. Apabila imej yang sama dirujuk dengan laluan yang tidak wujud, PDF terhasil cuma 1139 bait, kerana imej itu dibuang tanpa amaran dan hanya teks yang tinggal. Gejalanya bukan PDF kosong sepenuhnya, tetapi imej tidak muncul, dan perbezaan saiz antara dua hasil itu ialah bukti yang anda boleh ukur sendiri.

fontembed dan fon yang berbeza

Atribut fontembed juga boolean. Dengan fontembed="yes", enjin membenamkan fon ke dalam PDF supaya dokumen kelihatan sama di mana-mana mesin. Tanpa pembenaman, PDF merujuk fon mengikut nama, dan mesin yang membuka fail itu akan menggantikan fon yang tiada dengan fon pengganti. Ini sebab biasa susun atur berubah dan teks kelihatan lari dari tempatnya apabila fail dibuka pada komputer lain.

Untuk teks bahasa Melayu, isu fon lebih ketara kerana tidak semua fon sistem menyokong aksara yang diperlukan. Pastikan fon yang anda guna wujud pada pelayan yang menjana PDF, dan hidupkan fontembed untuk PDF yang akan dihantar kepada orang lain. Satu jadual gejala dan tindakannya ada di bawah.

Kenapa PDF berbeza antara dua pelayan

Apabila PDF yang sama kelihatan berbeza pada dua pelayan, selalunya salah satu daripada empat punca ini:

1. localurl tidak ditetapkan. Pada pelayan yang menjana PDF, imej relatif diselesaikan dari direktori yang berbeza atau melalui HTTP, jadi imej yang wujud pada satu pelayan gagal pada pelayan lain. Hasilnya ialah PDF yang kekurangan imej pada satu sisi sahaja.
2. Fon sistem berbeza. Dua pelayan yang memasang fon berbeza akan merender PDF yang berbeza, walaupun kodnya sama. PDF yang tidak membenamkan fon bergantung sepenuhnya pada mesin yang membukanya.
3. Versi enjin berbeza. Tingkah laku <cfdocument> berubah antara versi Lucee dan antara Lucee dengan Adobe ColdFusion. Kod yang berjalan pada versi baharu boleh merender berbeza pada versi lama, terutama dari segi saiz halaman dan jarak.
4. Sandbox dan kebenaran menulis. <cfdocument> dengan filename memerlukan kebenaran menulis pada direktori sasaran. Pada pelayan dengan sandbox ketat, penulisan itu gagal atau dihalang secara senyap, jadi fail tidak pernah tercipta.

Ujian pantas untuk mengasingkan punca ialah menjana PDF yang sama pada kedua-dua pelayan dengan kandungan teks sahaja, tanpa imej. Kalau saiz dan rupa teks itu sama, punca perbezaan adalah pada imej atau fon, bukan pada tag.

Halaman kosong: ralat selepas header dihantar

Halaman kosong sering bermakna ralat berlaku selepas pengepala HTTP sudah dihantar kepada pelayar. Apabila Lucee sudah menghantar status dan pengepala, ia tidak boleh lagi menghantar halaman ralat, jadi ralat itu hanya dicatat dalam log manakala pelayar menerima 200 dengan badan kosong atau terputus. Dalam rig, ujian yang menghantar PDF dan kemudian melontar ralat masih membalas 200 dengan jenis kandungan application/pdf, tetapi ralat itu tidak pernah sampai kepada pengguna.

Inilah sebabnya menyemak log pelayan adalah langkah pertama yang betul. Kalau PDF kosong dan tiada mesej di skrin, ralatnya hampir pasti ada dalam log. Rujuk panduan memantau log untuk cara membaca log Lucee, dan panduan asas cfdocument untuk atribut penuh.

Gejala, punca dan tindakan

Bukti sebenar dari rig

Semua angka di bawah dijana dan diukur pada pelayan Lucee sebenar, bukan dibaca daripada dokumentasi. Setiap fail ditulis ke cakera dan saiznya dibaca semula dengan getFileInfo.

PDF teks (name + cffile)      : len(dok)=1254, saiz fail=1254 bait
PDF teks (filename)           : saiz fail=1150 bait
PDF kosong (badan tiada isi)  : saiz fail=790 bait
PDF dengan imej (localurl=yes): saiz fail=1874 bait
PDF imej hilang (laluan salah): saiz fail=1139 bait
Halaman lupa keluarkan PDF    : HTTP 200, text/html, badan 2 bait

Perhatikan jurang antara 1874 bait dan 1139 bait. Kedua-duanya dijana daripada kod yang hampir sama, tetapi satu kehilangan imej. Itulah cara paling cepat untuk mengesan imej yang gagal dibenamkan tanpa membuka fail PDF: ukur saiznya dan bandingkan dengan saiz yang anda jangka.

Cara menguji sendiri

Salin blok pertama ke dalam fail .cfm pada pelayan anda, jalankan, dan baca saiz yang dicetak. Kalau saiznya sifar, anda menghadapi isu pengeluaran. Kalau saiznya beberapa ratus bait tetapi anda menjangka imej, semak localurl dan laluan imej. Kalau PDF wujud pada satu pelayan dan tiada pada pelayan lain, semak kebenaran menulis direktori sasaran dan bandingkan versi enjin kedua-dua pelayan.

Pengendalian imej dalam CFML diterangkan lebih lanjut dalam artikel tentang imej, manakala manipulasi PDF selepas ia dijana, seperti mencantum dan memecah halaman, dibincangkan dalam artikel tentang cfpdf.

Soalan Lazim

Kenapa PDF cfdocument saya kosong?

Kemungkinan besar anda menjana PDF ke dalam name tetapi terlupa menulis atau menghantarnya. Tambah cffile atau cfcontent untuk mengeluarkan pemboleh ubah itu, atau guna filename supaya enjin menulis terus.

Apakah perbezaan name dengan filename?

name menyimpan PDF dalam pemboleh ubah memori yang perlu anda keluarkan sendiri, manakala filename menulis terus ke fail. Pilih name apabila anda mahu memproses binari dahulu, dan filename apabila anda mahu fail terus tersedia.

Kenapa imej dalam PDF saya tidak muncul?

localurl ialah boolean, bukan laluan. Tetapkan localurl="yes" supaya imej relatif dibaca dari cakera, atau rujuk imej dengan laluan mutlak yang boleh diselesaikan. Imej yang gagal diselesaikan dibuang secara senyap, jadi PDF terhasil tanpa imej dan tanpa ralat.

Kenapa PDF berbeza antara dua pelayan?

Biasanya kerana fon sistem berbeza, versi enjin berbeza, localurl tidak ditetapkan, atau kebenaran menulis berbeza. Hidupkan fontembed dan selaraskan fon serta versi enjin pada kedua-dua pelayan.

Kenapa halaman saya kosong tanpa sebarang ralat?

Ralat itu berlaku selepas pengepala dihantar, jadi Lucee tidak dapat menghantar halaman ralat dan hanya mencatatnya dalam log. Semak log pelayan untuk mencari punca sebenar.

Sumber

• https://docs.lucee.org/reference/tags/document.html
• https://docs.lucee.org/reference/tags/file.html
• https://www.lucee.org