Nedávno som narazil na frustrujúci problém: zvýrazňovanie syntaxe fungovalo perfektne pri lokálnom spustení zola serve, ale po nasadení na Cloudflare Pages úplne zmizlo. Tu je opísané, ako som problém diagnostikoval a vyriešil.

Príznaky #

Problém sa prejavoval dvoma spôsobmi:

  1. Vizuálny rozdiel: Lokálne mali moje bloky kódu správne zvýrazňovanie syntaxe s farbami, ale na nasadenom webe vyzerali ako prostý text bez akéhokoľvek štýlovania.

  2. Prehliadač HTML odhalil problém: Pri skúmaní vygenerovaného HTML lokálne som videl inline štýly s farebnými vlastnosťami:

<span style="color:#bf616a;">#!/bin/bash</span>

Ale na nasadení Cloudflare Pages mali rovnaké elementy prázdne atribúty štýlov:

<span style="">#!/bin/bash</span>

Počiatočné pátranie #

Moja prvá domnienka bola, že ide o problém s konfiguráciou buildu Zola. Používal som Cloudflare Pages s vlastným nastavením buildu cez UNSTABLE_PRE_BUILD:

asdf plugin add zola https://github.com/salasrod/asdf-zola && asdf install zola 0.20.0 && asdf global zola 0.20.0

Spočiatku som podozrieval:

  • Chýbajúce generovanie CSS počas buildu
  • Nesprávne nastavenia config.toml pre zvýrazňovanie syntaxe
  • Rozdiely v prostredí buildu medzi lokálnym a Cloudflare

Skutočný vinník: Content Security Policy #

Prelom nastal, keď som skontroloval konzolu prehliadača a našiel viacero chýb CSP (Content Security Policy):

Content-Security-Policy: The page's settings blocked an inline style (style-src-attr) from being applied because it violates the following directive: "style-src 'self'"

Ďalšie súvisiace chyby zahŕňali:

Loading failed for the <script> with source "https://static.cloudflareinsights.com/beacon.min.js/vcd15cbe7772f49c399c6a5babf22c1241717689176015".
Content-Security-Policy: The page's settings blocked a script (script-src-elem) at https://static.cloudflareinsights.com/beacon.min.js/... from being executed because it violates the following directive: "script-src 'self'"
Content-Security-Policy: The page's settings blocked a style (style-src-elem) at https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:ital,wght@0,400;0,700;1,400;1,700&display=swap from being applied because it violates the following directive: "style-src 'self'"

Skutočná príčina #

Problém nebol vôbec v procese buildu Zola. Cloudflare Pages správne generovalo HTML s inline štýlmi, ale moja príliš reštriktívna Content Security Policy ich za behu odstraňovala.

Môj pôvodný súbor _headers bol:

/*
  X-Frame-Options: DENY
  Strict-Transport-Security: max-age=31536000; includeSubDomains
  Content-Security-Policy: default-src 'self'; script-src 'self'; object-src 'none'; style-src 'self'; img-src 'self'; frame-ancestors 'none';
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin

Direktíva style-src 'self' blokovala všetky inline štýly vrátane zvýrazňovania syntaxe Zola.

Riešenie #

Aktualizoval som súbor static/_headers, aby povoloval potrebné zdroje pri zachovaní bezpečnosti:

/*
  X-Frame-Options: DENY
  Strict-Transport-Security: max-age=31536000; includeSubDomains
  Content-Security-Policy: default-src 'self'; script-src 'self' https://static.cloudflareinsights.com; object-src 'none'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; img-src 'self'; font-src 'self' https://fonts.gstatic.com; connect-src 'self' https://cloudflareinsights.com; frame-ancestors 'none';
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin

Kľúčové zmeny #

  1. 'unsafe-inline' v style-src: Povoľuje inline štýly zvýrazňovania syntaxe Zola
  2. https://fonts.googleapis.com v style-src: Umožňuje CSS Google Fonts
  3. https://fonts.gstatic.com v font-src: Umožňuje načítanie súborov Google Fonts
  4. https://static.cloudflareinsights.com v script-src: Aktivuje Cloudflare Analytics
  5. https://cloudflareinsights.com v connect-src: Umožňuje analytické pripojenia

Ponaučenia #

  1. Konzola prehliadača je váš priateľ: Chyby CSP v konzole okamžite ukázali na skutočný problém a ušetrili hodiny ladenia konfigurácie Zola.

  2. Kompromisy medzi bezpečnosťou a funkčnosťou: Hoci 'unsafe-inline' mierne znižuje bezpečnosť, je nevyhnutný pre mnoho generátorov statických stránok, ktoré sa spoliehajú na inline štýly.

  3. Testujte v produkcii: Takéto problémy sa prejavia len v nasadenom prostredí, nie počas lokálneho vývoja.

  4. Ladenie CSP: Nástroje ako curl -I môžu pomôcť overiť, ktoré hlavičky sa podávajú:

    curl -I https://peterbabic.com | grep -i content-security-policy

Po nasadení aktualizovaných hlavičiek zvýrazňovanie syntaxe fungovalo perfektne a všetky chyby v konzole zmizli. Oprava bola jednoduchá, keď bol identifikovaný skutočný problém – niekedy problém nie je tam, kde ho najprv hľadáte. Enjoy!

Odkazy #