क्यों `serve` एक भद्दा साइट दिखा रहा था जबकि `publishSite` पूर्ण था

Table des matières

दृश्य: चार स्क्रीनशॉट, दो रेंडर
- Rendu local
- �ऑनलाइन रेंडर
निदान : serve सही फ़ोल्डर की ओर इशारा नहीं कर रहा था
मूल कारण: JBake CLI ऐसा काम नहीं करता है
समाधान : स्थिति-आधारित तर्क, फ़्लैग नहीं
curl के साथ त्वरित सत्यापन
यह बग घातक क्यों था?
निष्कर्ष

पढ़ने का समय: 10 minutes

क्या आप वह क्षण जानते हैं जब आपका स्थानीय साइट कुछ भी नहीं दिखता, लेकिन एक बार ऑनलाइन तैनात करने पर सब कुछ सही हो जाता है? यही मेरे साथ मेरे Gradle JBake प्लगइन के साथ हुआ। काम`serve`वर्गाकार बटन दिखा रहा था, काली पृष्ठभूमि पर गहरा टेक्स्ट, और एक अजीब रूप से गायब CSS. फिर भी`publishSite`वह समान साइट उत्पन्न कर रहा था — और वह निर्दोष था। दोषी CSS नहीं था, न ब्राउज़र, न कैश। यह कोटलिन की एक कोड लाइन थी — और कमांड लाइन तर्कों के साथ एक बुरी आदत।

सामग्री: []

दृश्य: चार स्क्रीनशॉट, दो रेंडर

यह सिस्टम क्रैश के बाद की बात थी। मैंने स्थानीय रेंडरिंग की तुलना करने के लिए चार स्क्रीनशॉट लिए थे (./gradlew serve`पर`localhost:8820) ऑनलाइन रेंडरिंग के साथ (`publishSite`प्रत्येक पृष्ठ पर दो स्क्रीनशॉट : ऊपर और नीचे.

Rendu local

पृष्ठ के शीर्ष— बटन Project और Template हैंछोटे, आयताकार, मानक रंगों (नीला और हरा) में। कार्ड Start Writing के पास एकसादा काला पृष्ठभूमि, फ्रेम के बिना

फ़ुटर— उपशीर्षक "नवीनतम लेख और संसाधन" हैलगभग अपठनीय, बहुत गहरा काले पृष्ठभूमि पर. ब्लॉग चित्रों के नीचे की तारीखें ("17 October 2013", आदि) हैंअनुपस्थित.

�ऑनलाइन रेंडर

पृष्ठ का शीर्ष— उसी बटन हैंबड़े, ovaux, चमकीला निऑन हरा, अपरकेस पाठ. कार्ड में एकगोल कोने वाला सफेद फ्रेम जिस पर ड्रॉप शैडो है.

फ़ूटर — Le sous-titre est स्पष्ट रूप से पढ़ने योग्य. तारीखें हैंदृश्य. अनुच्छेदों के कार्ड्स कुछ हैंगोल कोनेऔर शीर्षक हैंबोल्ड.

पहला रिफ्लेक्स: थीम। मैं डायनामिक थीम सिस्टम (हल्का, गहरा, high-contrast) आधारित उपयोग करता हूँ।localStorage. शायद local store ने high-contrast थीम ट्रिगर की थी? नहीं। मैंने पहले ही लिख दिया थाhttps://cheroliv.com/blog/2025/0098_preloading_css_variable_post.html[थीम्स के प्रीलोडिंग पर एक पूरा लेख], मुझे पता है कि यह कैसे काम करता है. और साथ ही, हाई-कंट्रास्ट मोड में भी, CSS संरचना (अंडाकार बटन, छायाएँ) वहां होनी चाहिए थी. वह वहां नहीं थी.

दूसरा प्रतिक्रिया: ब्राउज़र कैश। नहीं, मैंने स्वच्छ प्रोफ़ाइल के साथ परीक्षण किया था। अंतर बना रहा था।

तीसरा प्रतिक्रिया :`serve`यह समान फ़ाइलों की सेवा नहीं दे रहा था`publishSite`.

निदान : `serve` सही फ़ोल्डर की ओर इशारा नहीं कर रहा था

मेरा प्लगइन Gradle`bakery`दो मुख्य कार्य हैं:

bake: स्थिर साइट में उत्पन्न करता है`build/bake/`
serve: एक स्थानीय वेब सर्वर शुरू करता है
publishSite: बढ़ता है`build/bake/`की ओर GitHub Pages

असहमति केवल वहां से आ सकती थी`serve`. Si publishSite`वह सही सामग्री प्रकाशित कर रहा था, यह है कि`build/bake/`अच्छा था. अगर`serve`वह कुछ और दिखा रहा था, इसका मतलब यह था कि यह उपयोगी नहीं था`build/bake/.

चलो कोड देखते हैं। में`SiteManager.kt`, काम`serve`इस प्रकार परिभाषित है :

SiteManager.kt — La tâche serve (version buggy)

tasks.register("serve", JavaExec::class.java) { task ->
    task.apply {
        mainClass.set("org.jbake.launcher.Main")
        classpath = jbakeRuntime
        environment("GEM_PATH", jbakeRuntime.asPath)
        jvmArgs(/* ... */)
        args = listOf(
            "-b", file(site.bake.srcPath).absolutePath,
            "-s", layout.buildDirectory.get()
                .asFile.resolve(site.bake.destDirPath)
                .absolutePath
        )
    }
}

org.jbake.launcher.Main`JBake CLI 2.7.0 का प्रवेश बिंदु है। आधार विचार: पारित करना-b`स्रोत फ़ोल्डर के लिए और`-s`लक्ष्य फ़ोल्डर के लिए, फिर सर्वर मोड शुरू करें। सिवाय इसके कि…

मूल कारण: JBake CLI ऐसा काम नहीं करता है

JBake 2.7.0 कुछ का इंतजार कर रहा हैस्थितिगत आर्गुमेंटस्रोत और गंतव्य के लिए, फिर वैकल्पिक फ्लैग। हस्ताक्षर है :

jbake <source> <destination> [options]

लेकिन मेरे कोड में, मैं लिख रहा था:

args = listOf("-b", "/path/to/site", "-s", "/path/to/build/bake")

JBake ने इसे इस तरह से समझा:

-b→ फ़्लैग "bake" का पार्स करें (बूलियन), उपभोग किया गया
/path/to/site→ बन जाता है स्थितीय आर्ग्युमेंट 1 (स्रोत)
-s→ पार्स फ़्लैग "serve" (बूलियन), सर्वर शुरूतुरंत
/path/to/build/bake→ बन जाता है एक अनाथ तर्क, अनदेखा या गलत तरीके से समझा गया

परिणाम: JBake ले रहा था`/path/to/site`comme स्रोत,गंतव्य को ध्यान में नहीं रखादी गई (build/bake), और यह अपने डिफ़ॉल्ट निर्देशिका का उपयोग कर रहा था (सचं`./output`या एक अस्थायी प्रतिलिपि). फ़ाइल`css/styles.css`बिल्ड इसलिए ओवरराइट कर दिया गया या अनदेखा कर दिया गया, और यह एक पुराना डिफ़ॉल्ट CSS (कस्टम चर नहीं, कोने गोल नहीं, छाया नहीं) था जो परोसा जा रहा था।

तुलना में,bake et publishSite`वे उपयोग करते हैंआधिकारिक JBake Gradle प्लगइन(`jbake-gradle-plugin) जो साफ़‑सुथरे ढंग से लिखता है में`build/bake/`Gradle API के माध्यम से। वे CLI के माध्यम से नहीं गुज़रते।

समाधान : स्थिति-आधारित तर्क, फ़्लैग नहीं

सुधार साधारण है — एक बार जब आप जानते हैं। स्रोत और गंतव्य को स्थिति आर्गुमेंट्स के रूप में पास करना ही पर्याप्त है, फिर`-s`अंत में:

SiteManager.kt — La tâche serve (version corrigée)

args = listOf(
    file(site.bake.srcPath).absolutePath,
    layout.buildDirectory.get()
        .asFile.resolve(site.bake.destDirPath)
        .absolutePath,
    "-s"
)

यह सब है। तीन पंक्तियाँ बदल दी गई हैं, बग ठीक हो गया।

प्लगिन की स्थानीय प्रकाशन के बाद (publishToMavenLocal), un `./gradlew serve`JBake को सही सिंटैक्स के साथ लॉन्च करें :

jbake /home/user/project/site /home/user/project/build/bake -s

और इस बार, JBake में अंतर्निहित Jetty सर्वर सामग्री को अच्छी तरह से परोसता है`build/bake/`— ऑनलाइन प्रकाशित जैसा ही

curl के साथ त्वरित सत्यापन

सुनिश्चित करने के लिए कि सर्वर सही सामग्री प्रदान कर रहा है, एक साधारण`curl`पुष्टि करता है कि`index.html`समाविष्ट है`data-bs-theme="light"`और कि`build/bake/css/styles.css`इसे 31 402 बाइट्स का भार होता है — उत्पन्न फ़ाइल के समान`bake`.

$ ./gradlew serve
# Dans un autre terminal :
$ curl -s http://localhost:8820/ | grep data-bs-theme
<html ... data-bs-theme="light" ...>

$ curl -I http://localhost:8820/css/styles.css
HTTP/1.1 200 OK
Content-Length: 31402
Content-Type: text/css

स्थानीय रेंडरिंग अबपिक्सेल-समानडिप्लॉयड रेंडरिंग पर.

यह बग घातक क्यों था?

क्या आप देखते हैं कि इसे पकड़ना क्यों कठिन था?

कोई स्पष्ट त्रुटि नहीं: JBake क्रैश नहीं हो रहा था। यह "कार्य कर रहा था", बस एक गलत फ़ोल्डर के साथ।
बिल्ड काम कर रहा था:`./gradlew bake`फ़ाइलों को सही तरीके से उत्पन्न कर रहा था`build/bake/`.
डिप्लॉयमेंट काम कर रहा था(No output)`publishSite`अच्छी सामग्री का प्रचार ऑनलाइन कर रहा था
केवल serve टूटा हुआ था: विकास कार्य, जिसे हम लगातार पुनरावृत्ति के लिए उपयोग करते हैं।
-key value` की आदतएक डेवलपर के रूप में, हम यूनिक्स CLI के वर्षों से प्रभावित होते हैं`-o output`, `-i input`JBake CLI एक अपवाद है — स्रोत और गंतव्य स्थितिपरक हैं।

निष्कर्ष

यदि आप JBake (या कोई CLI टूल) को लपेटने वाला एक Gradle प्लगइन बनाए रखते हैं,तर्कों के दस्तावेज़ पढ़ें即使你认为你认识它们。一个隐含的假设(-s= "set destination") यह आपको दृश्य डिबगिंग में घंटे खर्च कर सकता है।

यहाँ, फिक्स लिटरल रूप से बदलने के लिए:

args = listOf("-b", src, "-s", dest)   // ❌ BUG

en :

args = listOf(src, dest, "-s")         // ✅ FIX

तीन टोकन स्थानांतरित हो गए, और मेरा स्थानीय साइट फिर से उत्पादन साइट जितना सुंदर बन गया।

पाठ: जब रेंडर स्थानीय और उत्पादन के बीच बिना स्पष्ट कारण के भिन्न हो, तो पहले pipeline के बारे में संदेह करें — CSS नहीं, ब्राउज़र नहीं, और बिल्कुल भी फ्रेमवर्क नहीं। अक्सर वह चरण जो रेंडर से ठीक पहले होती है, धोखा देती है।