從76到100：達成完美的Lighthouse分數
重點摘要： 一個個人作品集網站從行動裝置Lighthouse效能分數76分、CLS 0.493，進步到全類別完美的100/100/100/100。這段旅程揭露了隱微的CSS載入問題、正規表達式臭蟲，以及一個特別狡猾的CSS變數覆寫問題，導致行動裝置上產生版面位移。
起點
這個網站是一個以FastAPI + Jinja2建構的作品集，搭配HTMX和Alpine.js提供互動性。初始的Lighthouse行動裝置審核結果：
| 指標 | 分數 |
|---|---|
| 效能 | 76 |
| 無障礙 | 91 |
| 最佳實踐 | 100 |
| SEO | 100 |
| CLS | 0.493 |
那個CLS數字相當慘烈。Google認為任何超過0.1的數值都是「差」。在0.493的情況下，頁面在載入時明顯地跳來跳去。
第一階段：無障礙快速修正
在處理效能之前，我先清理了無障礙問題以建立基準線：
表單標籤
將裝飾性的span改為適當的<label>元素：
<!-- Before: span with aria-describedby -->
<span class="contact-form__label">Email</span>
<input id="email" aria-describedby="...">
<!-- After: proper label association -->
<label for="email" class="contact-form__label">Email</label>
<input id="email">
對比度
頁尾標題和表單標籤使用了--color-text-tertiary（40%不透明度的白色）。提升至--color-text-secondary（65%不透明度）以符合WCAG AA 4.5:1對比度要求。
冗餘的替代文字
社群媒體圖示有像「LinkedIn icon」這樣的替代文字，但它們位於已有aria-labels的連結內。改為alt=""搭配aria-hidden="true"，避免螢幕閱讀器重複朗讀。
相同的連結文字
多個「View Case Study」連結對螢幕閱讀器來說無法區分。加入了包含專案名稱的aria-label屬性：
<a href="/work/introl" aria-label="View Introl Branding case study">
View Case Study
</a>
結果： 無障礙從91分躍升至100分。
第二階段：阻塞渲染的CSS問題
Lighthouse顯示LCP breakdown中有2,460毫秒的「Element render delay」。罪魁禍首：一個同步載入的CSS檔案阻塞了首次繪製。
<!-- The problem: render-blocking stylesheet -->
<link rel="stylesheet" href="/static/css/styles.min.css">
瀏覽器必須下載並解析整個25KB的樣式表，才能繪製任何內容。
解決方案：關鍵CSS + 非同步載入
步驟一： 將關鍵（首屏）CSS提取到單獨的檔案中，內嵌在<head>裡。
步驟二： 使用media="print"技巧非同步載入完整樣式表：
<!-- Critical CSS inlined for instant first paint -->
<style>{% include "components/_critical.css" %}</style>
<!-- Full CSS loaded async (doesn't block render) -->
<link rel="stylesheet" href="/static/css/styles.min.css"
media="print" onload="this.media='all'">
<noscript>
<link rel="stylesheet" href="/static/css/styles.min.css">
</noscript>
media="print"屬性告訴瀏覽器「這個樣式表不是螢幕渲染所需的」，因此不會造成阻塞。載入完成後，onload處理器將其切換為media="all"。
關鍵CSS提取腳本
我寫了一個Python腳本來自動提取首屏元件的關鍵CSS：
CRITICAL_PREFIXES = [
".container",
".header",
".nav",
".hero",
".personal-photos",
]
def extract_critical_css(css_content: str) -> str:
# Strip comments to prevent regex pollution
css_no_comments = re.sub(r'/\*[\s\S]*?\*/', '', css_content)
# Extract :root variables
# Extract base reset rules
# Extract component rules by prefix
# Extract media queries containing critical selectors
...
結果： LCP元素渲染延遲從2,460毫秒降至約300毫秒。
第三階段：CLS噩夢開始
實作非同步CSS後，CLS竟然變更糟了——跳到0.119。Lighthouse顯示<main>是位移元素。
臭蟲 #1：CSS註解污染正規表達式
提取腳本使用正規表達式來匹配選擇器：
rule_pattern = r"([.#\w][^{]+)\{([^}]+)\}"
問題：提取前沒有先移除CSS註解。像這樣的註解：
/* Hero Section - Editorial */
.hero { ... }
會導致正規表達式從「Hero Section」匹配到左大括號，產生格式錯誤的選擇器，無法通過前綴檢查。關鍵的.hero樣式被靜默地忽略了。
修正： 在任何正規表達式操作之前先移除註解：
css_no_comments = re.sub(r'/\*[\s\S]*?\*/', '', css_content)
臭蟲 #2：媒體查詢內的規則被提取為獨立規則
正規表達式匹配了媒體查詢內部的規則，並將它們提取為獨立規則：
/* Full CSS structure */
.hero__title { font-size: 5rem; } /* Desktop */
@media (max-width: 768px) {
.hero__title { font-size: 1.875rem; } /* Mobile */
}
腳本將兩條規則都提取到頂層：
/* Broken critical CSS */
.hero__title { font-size: 5rem; }
.hero__title { font-size: 1.875rem; } /* Overrides desktop! */
在行動裝置上，標題從關鍵CSS取得行動版尺寸來渲染，然後……維持不變，因為完整CSS有相同的規則。但在桌面版上，行動版的覆寫卻錯誤地套用了。
修正： 追蹤媒體查詢的位置範圍，跳過其中的規則：
# Find all media query ranges
media_ranges = []
for match in re.finditer(media_pattern, css_no_comments):
media_ranges.append((match.start(), match.end()))
def is_inside_media_query(pos: int) -> bool:
return any(start <= pos < end for start, end in media_ranges)
# Skip rules inside media queries during extraction
for match in re.finditer(rule_pattern, css_no_comments):
if is_inside_media_query(match.start()):
continue # Will be included with full media query block
# ... extract rule
第四階段：100vh假說
CLS仍然是0.116。理論：如果首屏以下的內容在初始繪製時不可見，就不會影響CLS。
將hero從85vh改為100vh：
.hero {
/* 100vh ensures nothing below fold is visible on initial paint */
min-height: 100vh;
}
結果： 沒有變化。CLS仍然是0.116。位移發生在視窗內部。
第五階段：找到真兇
Lighthouse幻燈片顯示hero文字在不同影格之間明顯地位移。不是淡入淡出——是水平移動。
深入調查哪些樣式影響水平定位：
- .hero__content使用padding: 0 var(--gutter)
- --gutter在:root中定義為48px
然後我找到了：
/* In full CSS, but NOT in critical CSS */
@media (max-width: 768px) {
:root {
--gutter: var(--spacing-md); /* 24px */
}
}
行動裝置上的事件順序：
- 關鍵CSS載入：
--gutter: 48px - Hero以48px側邊內距渲染
- 完整CSS非同步載入
- 媒體查詢將
--gutter設為24px - Hero內距從48px縮小到24px
- 文字重排並位移 = CLS 0.116
修正方式
將:root媒體查詢作為關鍵CSS的一部分提取：
# Extract :root media queries (variable overrides are critical)
root_media_pattern = r"@media[^{]+\{\s*:root\s*\{[^}]+\}\s*\}"
for match in re.finditer(root_media_pattern, css_no_comments):
critical_rules.append(match.group())
現在關鍵CSS包含：
:root { --gutter: 48px; /* ... */ }
@media (max-width: 768px) {
:root { --gutter: var(--spacing-md); }
}
行動裝置從一開始就以正確的24px間距渲染。當完整CSS載入時，--gutter已經是24px——沒有變化、沒有位移。
第六階段：CSP與Alpine.js
還有一個問題：Alpine.js因為內容安全政策違規而拋出主控台錯誤。Alpine內部使用動態表達式求值。
# In security headers middleware
CSP_DIRECTIVES = {
"script-src": "'self' 'unsafe-inline' 'unsafe-eval'",
# ...
}
Alpine.js的表達式解析需要'unsafe-eval'指令。替代方案是使用Alpine的CSP相容建構版本，但有一些限制。
最終結果
| 指標 | 之前 | 之後 |
|---|---|---|
| 效能 | 76 | 100 |
| 無障礙 | 91 | 100 |
| 最佳實踐 | 100 | 100 |
| SEO | 100 | 100 |
| CLS | 0.493 | 0.033 |
| LCP | 2.6秒 | 0.8秒 |
證據
桌面版審核顯示四個類別皆為滿分：
行動版審核——最重要的那個——同樣達到完美分數：
重要收穫
1. CSS變數可能導致CLS
CSS自訂屬性的媒體查詢覆寫在DevTools的計算樣式面板中是不可見的——您只會看到最終值。如果您的關鍵CSS未包含變數覆寫，當完整樣式表載入時就會產生版面位移。
2. 關鍵CSS提取並不簡單
簡單的正規表達式方法會在以下情況失敗：
- CSS註解（可能污染選擇器匹配）
- 媒體查詢內的規則（必須保留在區塊內）
- :root媒體查詢（變數變更會影響所有元素）
3. media="print"技巧確實有效
使用media="print" onload="this.media='all'"載入非關鍵CSS，是一種延遲樣式表載入的正當方式，無需複雜的JavaScript。
4. 除錯CLS需要幻燈片檢視
Lighthouse的幻燈片檢視能精確顯示位移發生的時間點。沒有它，您只能盲猜。被標記為「位移」的元素可能只是表象——要尋找造成它位移的根本原因。
5. 100vh的Hero區段不僅是美學考量
如果您的hero填滿了整個視窗，首屏以下的內容就不會影響CLS，因為在使用者捲動之前不會被測量。
技術堆疊
- 後端： FastAPI + Jinja2
- 前端： HTMX + Alpine.js（自架，未使用CDN）
- CSS： 純CSS搭配自訂屬性，無預處理器
- 最佳化： 自訂Python腳本進行關鍵CSS提取
- 託管： Railway搭配GZip壓縮與不可變快取
使用的工具
- Lighthouse（Chrome DevTools）
- Lighthouse幻燈片檢視用於CLS除錯
grep和regex101.com用於CSS分析- Python用於關鍵CSS提取腳本
- iTerm 2
- Claude Code CLI搭配Opus 4.5以及大量的ultrathink