vite-plugin-react-shopify 1.1.0 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # vite-plugin-react-shopify
 
-使用 React 组件编写 Shopify 主题的 Section、Block 和 Template。在构建时通过 SSG（Static Site Generation）将 React 组件编译为 Shopify Liquid 文件，运行时由 React 进行水合（hydration）。
+使用 React 组件编写 Shopify 主题的 Section、Block、Snippet 和 Template。在构建时通过 SSG（Static Site Generation）将 React 组件编译为 Shopify Liquid 文件，运行时由 React 进行水合（hydration）。
 
 ## 安装
 
@@ -17,7 +17,7 @@ import vitePluginShopify from "vite-plugin-react-shopify";
 export default {
   plugins: [
     vitePluginShopify({
-      themeRoot: ".",           // 主题根目录，默认 "./"
+      themeRoot: ".",            // 主题根目录，默认 "./"
       sourceCodeDir: "frontend", // 源码目录，默认 "frontend"
     }),
   ],
@@ -27,14 +27,19 @@ export default {
 ```tsx
 // frontend/sections/HelloWorld.tsx
 import type { ShopifyMeta } from "vite-plugin-react-shopify";
+import { useSectionSettings } from "vite-plugin-react-shopify/runtime";
 
 export const shopifyMeta = {
   name: "Hello World",
+  settings: [
+    { type: "text", id: "title", label: "Title", default: "Hello, World!" },
+  ],
   presets: [{ name: "Hello World" }],
 } satisfies ShopifyMeta;
 
 export default function HelloWorld() {
-  return <h1>Hello, World!</h1>;
+  const { value: title } = useSectionSettings("title");
+  return <h1>{title}</h1>;
 }
 ```
 
@@ -42,8 +47,6 @@ export default function HelloWorld() {
 
 ### 开发
 
-使用 `vite build --watch` 进行本地开发。Vite 8 的 Rolldown 内置增量构建缓存，文件变更时仅重新构建受影响的模块。
-
 ```bash
 # 终端 1: 启动 Vite 构建监听
 pnpm dev    # → vite build --watch
@@ -52,17 +55,7 @@ pnpm dev    # → vite build --watch
 shopify theme dev
 ```
 
-Vite 监听文件变化 → 增量构建 → 写入磁盘 → Shopify CLI 检测到变化 → 推送主题 → 编辑器热更新。watch 模式下产物不压缩、附带 inline sourcemap，方便在浏览器中调试。
-
-```json
-// package.json
-{
-  "scripts": {
-    "dev": "vite build --watch",
-    "build": "vite build"
-  }
-}
-```
+Vite 监听文件变化 → 增量构建 → 写入磁盘 → Shopify CLI 检测到变化 → 推送主题 → 编辑器热更新。
 
 ---
 
@@ -75,178 +68,169 @@ my-theme/
 │   │   └── HelloWorld.tsx
 │   ├── blocks/
 │   │   └── TextBlock.tsx
+│   ├── snippets/
+│   │   └── MySnippet.tsx
 │   └── templates/
 │       └── index.tsx
 ├── sections/                 ← 生成的 Liquid + 原生 Liquid
 ├── blocks/
-├── templates/
 ├── snippets/
-│   └── shopify-importmap.liquid  ← 自动生成的 importmap
+├── templates/
 └── assets/                   ← Vite 构建产物（可通过 buildDir 配置子目录）
 ```
 
-源码放在 `frontend/` 下，按 Shopify 类型分目录。构建后生成对应的 `.liquid` 文件到主题根目录的 `sections/`、`blocks/`、`templates/` 下。
+---
+
+## Settings 和 Liquid 数据读取
+
+### 核心 API
+
+所有 Liquid 数据的读取通过统一的基础 hook `useLiquid(expr)`：
+
+```tsx
+import {
+  useLiquid,
+  useLiquidValues,
+  useSectionSettings,
+  useBlockSettings,
+  useSnippetParams,
+  useBlockParams,
+} from "vite-plugin-react-shopify/runtime";
+```
+
+| Hook | 用途 | 内部等价于 |
+|------|------|-----------|
+| `useLiquid(expr)` | 读取任意 Liquid 表达式 | — |
+| `useLiquidValues({ key: expr })` | 批量读取多个表达式 | N 次 `useLiquid` |
+| `useSectionSettings(key)` | Section setting | `useLiquid("section.settings.KEY")` |
+| `useBlockSettings(key)` | Block setting | `useLiquid("block.settings.KEY")` |
+| `useSnippetParams(key)` | Snippet param | `useLiquid("KEY")` |
+| `useBlockParams(key)` | Block param | `useLiquid("KEY")` |
+
+所有 hook 返回 `{ value: string | undefined }`（`useLiquidValues` 返回 `{ values: Record }`）。
+
+```tsx
+export default function ProductBanner() {
+  const { value: title } = useSectionSettings("title");
+  const { value: price } = useLiquid("product.price");
+  const { values: p } = useLiquidValues({
+    name: "product.title",
+    desc: "product.description",
+  });
+
+  return (
+    <div>
+      <h1>{title}</h1>
+      <span>{price}</span>
+      <p>{p.name}</p>
+      <div dangerouslySetInnerHTML={{ __html: p.desc || "" }} />
+    </div>
+  );
+}
+```
+
+### 工具函数
+
+```ts
+import { parseLiquidBoolean, parseLiquidNumber } from "vite-plugin-react-shopify/runtime";
+
+// SSR-safe: Liquid 表达式字符串 → 默认值；客户端 → 实际解析
+const count = parseLiquidNumber(s.initial, 0);
+const show = parseLiquidBoolean(s.show_banner);
+```
+
+### 水合流程
+
+1. **SSR**：hook 返回 `{{ expr }}` 字符串，同时注册表达式到追踪器
+2. **Liquid 组装**：生成统一 `<script type="application/json" data-ssg-liquid>` JSON bridge
+3. **Shopify 渲染**：Liquid 引擎替换表达式为实际值，bridge JSON 包含序列化后的值
+4. **客户端水合**：`LiquidDataProvider` 接收 bridge JSON → hook 通过 `useContext` 读取
 
 ---
 
 ## 组件约定
 
-每个 React 组件必须导出两样东西：
+每个 React 组件必须导出：
 
 ### 1. `shopifyMeta` — Shopify Schema 定义
 
 ```tsx
 export const shopifyMeta = {
-  name: "组件名称",           // 必填，在 Shopify 编辑器中显示的名称
-  type: "section",            // 可选，覆盖目录推断的类型
+  name: "组件名称",
+  type: "section",            // 可选，覆盖目录推断
   tag: "section",             // 可选，外层 HTML 标签，默认 "div"
-  class: "custom-class",      // 可选，外层附加的 CSS 类名
-  limit: 1,                   // 可选，每页最大数量
-  max_blocks: 10,             // 可选，最大子 block 数
-  settings: [...],            // 可选，设置项
-  blocks: [...],              // 可选，接受的子 block 类型
-  presets: [...],             // 可选，编辑器预设
-  enabled_on: {...},          // 可选，启用条件
-  disabled_on: {...},         // 可选，禁用条件
-  templates: [...],           // 可选，适用的模板
+  class: "custom-class",      // 可选，外层 CSS 类名
+  limit: 1,
+  max_blocks: 10,
+  settings: [...],
+  blocks: [...],
+  presets: [...],
 } satisfies ShopifyMeta;
 ```
 
 ### 2. `default export` — React 组件
 
 ```tsx
-export default function MyComponent(props) {
+export default function MyComponent() {
   return <div>...</div>;
 }
 ```
 
 ### 类型推断
 
-文件名和目录决定目标类型：
-
 | 源码路径 | 目标类型 | 生成文件 |
 |----------|----------|----------|
 | `frontend/sections/X.tsx` | `section` | `sections/react-x.liquid` |
 | `frontend/blocks/X.tsx` | `block` | `blocks/react-x.liquid` |
 | `frontend/templates/X.tsx` | `template` | `templates/page.react-x.liquid` |
-
-可通过 `shopifyMeta.type` 覆盖。
+| `frontend/snippets/X.tsx` | `snippet` | `snippets/react-x.liquid` |
 
 ---
 
 ## 设置 (Settings)
 
-使用 `SettingSchema` 类型定义设置项。`SettingSchema` 是根据 `type` 字段判别（discriminated union）的联合类型 —— 每种 type 只接受 Shopify 文档中合法的字段，无效字段会在编译时报错：
-
 ```tsx
 import type { SettingSchema } from "vite-plugin-react-shopify";
 
 const settings = [
-  {
-    type: "text",
-    id: "title",
-    label: "Title",
-    default: "Hello",
-  },
-  {
-    type: "select",
-    id: "layout",
-    label: "Layout",
-    default: "grid",
-    options: [
-      { value: "grid", label: "Grid" },
-      { value: "list", label: "List" },
-    ],
-  },
-  {
-    type: "range",
-    id: "columns",
-    label: "Columns",
-    default: 3,
-    min: 1,
-    max: 6,
-    step: 1,
-  },
+  { type: "text", id: "title", label: "Title", default: "Hello" },
+  { type: "select", id: "layout", label: "Layout", default: "grid",
+    options: [{ value: "grid", label: "Grid" }, { value: "list", label: "List" }] },
+  { type: "range", id: "columns", label: "Columns", default: 3, min: 1, max: 6, step: 1 },
 ] satisfies SettingSchema[];
-
-// 也可以直接引用具体类型：
-import type { SelectSetting, RangeSetting } from "vite-plugin-react-shopify";
 ```
 
 ### 基本输入类型
 
-| 类型 | 额外字段 | `default` |
-|------|----------|-----------|
-| `checkbox` | — | 可选 `boolean` |
-| `number` | `placeholder` | 可选 `number` |
-| `radio` | `options`（必填） | 可选 `string` |
-| `range` | `min`（必填）、`max`（必填）、`step`、`unit` | **必填** `number` |
-| `select` | `options`（必填） | 可选 `string` |
-| `text` | `placeholder` | 可选 `string` |
-| `textarea` | `placeholder` | 可选 `string` |
+| 类型 | 额外字段 |
+|------|----------|
+| `checkbox` | `default`（`boolean`） |
+| `number` | `placeholder` |
+| `radio` | `options`（必填） |
+| `range` | `min`（必填）、`max`（必填）、`step`、`unit` |
+| `select` | `options`（必填） |
+| `text` | `placeholder` |
+| `textarea` | `placeholder` |
 
 ### 专用输入类型
 
-| 类型 | 额外字段 |
-|------|----------|
-| `article` | —（不支持 `default`） |
-| `article_list` | `limit` |
-| `blog` | —（不支持 `default`） |
-| `collection` | —（不支持 `default`） |
-| `collection_list` | `limit` |
-| `color` | — |
-| `color_background` | — |
-| `color_scheme` | — |
-| `color_scheme_group` | `definition`（必填）、`role`（必填） |
-| `font_picker` | —（`default` **必填** `string`） |
-| `html` | `placeholder` |
-| `image_picker` | —（不支持 `default`） |
-| `inline_richtext` | — |
-| `link_list` | —（`default` 限制为 `"main-menu"` / `"footer"`） |
-| `liquid` | — |
-| `metaobject` | `metaobject_type`（必填） |
-| `metaobject_list` | `metaobject_type`（必填）、`limit` |
-| `page` | —（不支持 `default`） |
-| `product` | —（不支持 `default`） |
-| `product_list` | `limit` |
-| `richtext` | — |
-| `text_alignment` | —（`default` 限制为 `"left"` / `"center"` / `"right"`） |
-| `url` | — |
-| `video` | —（不支持 `default`） |
-| `video_url` | `accept`（必填）、`placeholder` |
-
-### 侧边栏类型（非输入，仅显示信息）
-
-`header`、`paragraph`、`line_break`。与输入类型不同，侧边栏类型不保存值，仅用于组织和描述设置项。使用 `content` 字段代替 `id`/`label`：
+`article`、`article_list`、`blog`、`collection`、`collection_list`、`color`、`color_background`、`color_scheme`、`color_scheme_group`、`font_picker`、`html`、`image_picker`、`inline_richtext`、`link_list`、`liquid`、`metaobject`、`metaobject_list`、`page`、`product`、`product_list`、`richtext`、`text_alignment`、`url`、`video`、`video_url`
 
-```tsx
-const settings = [
-  { type: "header", content: "Typography", info: "Customize text styles below." },
-  { type: "font_picker", id: "heading_font", label: "Heading font", default: "helvetica_n4" },
-  { type: "paragraph", content: "Set your brand colors for buttons and accents." },
-  { type: "color", id: "accent_color", label: "Accent color", default: "#000000" },
-  { type: "line_break" },
-  { type: "checkbox", id: "dark_mode", label: "Enable dark mode", default: false },
-] satisfies SettingSchema[];
+### 侧边栏类型
 
-Setting 的 `id` 会作为 React 组件的 prop 名传入。Shopify 编辑器修改 setting 后，水合层会读取 `{{ section.settings | json }}` 将最新值传给组件。设置值通过 `useShopifySettings()` hook 读取。
+`header`、`paragraph`、`line_break`。使用 `content` 字段，不保存值。
 
 ---
 
 ## 预设 (Presets)
 
-预设让组件可以在编辑器中通过"添加 Section/Block"面板直接添加：
-
 ```tsx
 export const shopifyMeta = {
   name: "Hero Banner",
   presets: [
     { name: "Hero (Light)", category: "Banners" },
-    {
-      name: "Hero (Dark)",
-      category: "Banners",
-      settings: { bg_color: "#000", text_color: "#fff" },
-    },
+    { name: "Hero (Dark)", category: "Banners",
+      settings: { bg_color: "#000", text_color: "#fff" } },
   ],
 } satisfies ShopifyMeta;
 ```
@@ -255,60 +239,56 @@ export const shopifyMeta = {
 
 ## 子 Block（嵌套）
 
-Section 或 Block 可以声明接受的子 block 类型：
-
 ```tsx
 export const shopifyMeta = {
   name: "Group",
-  blocks: [{ type: "@theme" }], // 接受所有主题 block
+  blocks: [{ type: "@theme" }],
 } satisfies ShopifyMeta;
 ```
 
 - `"@theme"` 接受当前主题中所有已注册的 block
-- `"类型名"` 只接受特定类型的 block（如 `"text"` 匹配 `blocks/text.liquid`）
-- 插件会自动在生成的 Liquid 中插入 `{% content_for 'blocks' %}`
+- 插件自动插入 `{% content_for 'blocks' %}`
 
 ---
 
-## CSS 样式
+## Snippet
 
-使用 CSS Module 为组件添加样式。CSS 会在构建时被内联到生成的 Liquid 的 `{% stylesheet %}` 块中，由 Shopify 统一注入到 `<head>`，避免 FOUC 和额外 HTTP 请求。
-
-```css
-/* frontend/sections/Hero.module.css */
-.hero {
-  display: grid;
-  padding: 2rem;
-}
-.hero-title {
-  font-size: 3rem;
-  font-weight: 700;
-}
-```
+通过 `params` 传参（而非 `settings`）：
 
 ```tsx
-// frontend/sections/Hero.tsx
-import styles from "./Hero.module.css";
+// frontend/snippets/ProductCard.tsx
+import { useSnippetParams } from "vite-plugin-react-shopify/runtime";
 
-export default function Hero() {
-  return (
-    <div className={styles["hero"]}>
-      <h1 className={styles["hero-title"]}>Title</h1>
-    </div>
-  );
+export const shopifyMeta = {
+  type: "snippet",
+  name: "Product Card",
+  params: ["title", "price"],
+} satisfies ShopifyMeta;
+
+export default function ProductCard() {
+  const { value: title } = useSnippetParams("title");
+  const { value: price } = useSnippetParams("price");
+  return <div><h3>{title}</h3><span>{price}</span></div>;
 }
 ```
 
-生成的 Liquid 中会包含：
+调用方式：`{% render 'react-product-card', title: 'Hello', price: '$10' %}`
+
+---
+
+## CSS 样式
+
+使用普通 CSS 文件为组件添加样式。CSS 会在构建时被内联到 Liquid 的 `{% stylesheet %}` 块中。多个组件共享的 CSS 自动提取为 snippet：
 
-```liquid
-{% stylesheet %}
-._hero_abc123{display:grid;padding:2rem}
-._hero-title_abc123{font-size:3rem;font-weight:700}
-{% endstylesheet %}
+```css
+/* frontend/sections/Hero.css */
+.hero { display: grid; padding: 2rem; }
 ```
 
-> **注意**：SSG 预渲染的 HTML 使用未经过 Vite hash 处理的类名。浏览器加载后 React 水合会替换为正确的 hash 类名。这是 CSS Module + SSG 的已知权衡。
+```tsx
+import "./Hero.css";
+export default function Hero() { return <div className="hero">...</div>; }
+```
 
 ---
 
@@ -316,182 +296,119 @@ export default function Hero() {
 
 ```ts
 vitePluginShopify({
-  // === 路径配置 ===
-  themeRoot: ".",              // 主题根目录
-  sourceCodeDir: "frontend",   // React 源码目录（相对于 themeRoot）
-  snippetFile: "shopify-importmap.liquid", // importmap 片段文件名
-  buildDir: "assets",          // Vite 构建产物输出目录（相对于 themeRoot）
-
-  // === 构建配置 ===
-  hash: false,                 // 产物文件名是否包含 content hash，默认 false
-
-  // === 调试 ===
-  debug: false,                // 启用详细日志输出
-
-  // === SSG 配置 ===
+  themeRoot: ".",                         // 主题根目录
+  sourceCodeDir: "frontend",              // React 源码目录
+  snippetFile: "shopify-importmap.liquid",// importmap 片段文件名
+  buildDir: "assets",                     // 构建产物输出目录
+  debug: false,                           // 详细日志
   ssg: {
-    directories: ["sections", "blocks", "templates"], // 扫描的目录
-    prefix: {                  // 生成文件的命名前缀
-      template: "page.react-", // templates → page.react-xxx.liquid
-      section: "react-",       // sections   → react-xxx.liquid
-      block: "react-",         // blocks     → react-xxx.liquid
+    directories: ["sections", "blocks", "templates", "snippets"],
+    prefix: {
+      template: "page.react-",
+      section: "react-",
+      block: "react-",
+      snippet: "react-",
     },
-    outputName: "",            // 自定义输出模板，留空使用前缀规则
+    outputName: "",                       // 自定义输出模板
+    cssPrefix: "css",                     // 共享 CSS snippet 前缀
   },
-
-  // === Import Map 配置 ===
   importMap: {
-    react: "https://esm.sh/react@19",
-    reactDomClient: "https://esm.sh/react-dom@19/client",
+    react: "{{ 'react.js' | asset_url }}",
+    reactDomClient: "{{ 'react-dom.js' | asset_url }}",
   },
 });
 ```
 
 ---
 
-## 命名约定
-
-### 默认命名规则
-
-| 源码文件 | 目标类型 | 生成文件 |
-|----------|----------|----------|
-| `frontend/sections/MySection.tsx` | section | `sections/react-my-section.liquid` |
-| `frontend/blocks/MyBlock.tsx` | block | `blocks/react-my-block.liquid` |
-| `frontend/templates/Index.tsx` | template | `templates/page.react-index.liquid` |
-
-- 组件文件名通过 `toKebabCase` 转换为 kebab-case：
-  - `HelloWorld` → `hello-world`
-  - `FAQSection` → `faq-section`
-- JS 产物默认使用稳定文件名（如 `assets/build/hello-world.js`），设置 `hash: true` 后启用 content hash（如 `assets/build/hello-world-aBc123.js`）
-
-### 自定义命名（`outputName`）
-
-```ts
-ssg: {
-  outputName: "{target}s/{kebab}"  // 按类型分目录，不添加前缀
-}
-```
-
-支持占位符：`{type}`、`{kebab}`、`{pascal}`、`{target}`。
-
----
-
-## 水合（Hydration）与编辑器事件
+## 水合与编辑器事件
 
 ### 水合流程
 
-1. **SSG 预渲染**：构建时 React 组件渲染为静态 HTML，嵌入 `<div data-ssg-hydrate>`
-2. **Settings 透传**：Liquid 中 `<script type="application/json" data-ssg-props>` 包含 `{{ section.settings | json }}`
-3. **Hydration JS**：Vite 为每个组件生成独立的 hydration chunk，读取 settings JSON 并调用 `hydrateRoot`
+1. **SSG 预渲染**：React 组件渲染为含 Liquid 表达式的 HTML，Liquid 组装器生成 `data-ssg-liquid` JSON bridge
+2. **Liquid 渲染**：Shopify 服务端替换表达式为实际值
+3. **Hydration JS**：Vite 为每个组件生成独立 hydration chunk，读取 JSON bridge 并调用 `hydrateRoot`
 
 ### 编辑器事件
 
-Hydration 脚本自动监听 Shopify 编辑器的 Section 生命周期事件：
-
 | 事件 | 行为 |
 |------|------|
-| `shopify:section:load` | Section 被添加或重新渲染时，重新 hydrate 组件 |
-| `shopify:section:unload` | Section 被删除或即将重新渲染时，unmount React 根节点 |
-
-当用户在编辑器中修改 setting 时：Shopify 重新渲染 Section HTML → 触发 `unload`（清理旧 root）→ 触发 `load`（用新 props 重新 hydrate）。
+| `shopify:section:load` | 重新 hydrate 组件 |
+| `shopify:section:unload` | unmount React 根节点 |
 
 ---
 
-## 运行时
-
-### Liquid 组件
-
-在 JSX 中嵌入原始 Liquid 代码：
-
-```tsx
-import { Liquid } from "vite-plugin-react-shopify/runtime";
+## 调试
 
-export default function Section() {
-  return (
-    <div>
-      <Liquid>{`{% if section.settings.show_title %}`}</Liquid>
-      <h1>Title</h1>
-      <Liquid>{`{% endif %}`}</Liquid>
-    </div>
-  );
-}
+```bash
+DEBUG=vite-plugin-shopify:* npx vite build
 ```
 
-### Import Map
+---
 
-插件自动生成 `snippets/shopify-importmap.liquid`，包含 React 和 ReactDOM 的 CDN import map。在主题 `layout/theme.liquid` 的 `<head>` 中引入：
+## 开发规范
 
-```liquid
-{% render 'shopify-importmap' %}
-```
+> 详见 `docs/hydration-issues.md`
 
----
+### JSX 子节点中相邻文本+表达式
 
-## 调试
+**必须使用模板字面量包裹**：
 
-插件提供了两种方式启用详细日志输出，方便诊断构建问题。
-
-### 方式一：插件选项
+```tsx
+// ❌ 水合失败：相邻文本节点不匹配
+<button>-{step}</button>
+<li>title = {title}</li>
 
-```ts
-vitePluginShopify({
-  debug: true,
-});
+// ✅ 模板字面量
+<button>{`-${step}`}</button>
+<li>{`title = ${title}`}</li>
 ```
 
-### 方式二：环境变量
+### useState 初始化
 
-```bash
-DEBUG=vite-plugin-shopify:* npx vite build
+**不能依赖 `useLiquid` 返回值**：
+
+```tsx
+// ❌ SSR 时 Number("{{ expr }}") = NaN → 不匹配
+const [count, setCount] = useState(Number(s.initial) || 0);
+
+// ✅ 固定默认值 + useEffect 同步
+const [count, setCount] = useState(0);
+useEffect(() => { setCount(parseLiquidNumber(s.initial, 0)); }, []);
 ```
 
-两种方式效果相同，都会输出详细的构建过程信息。
+### 条件渲染
 
-### Debug 输出示例
+**不用 `{value && <Element />}`**，用 `hidden` 属性：
 
-启用 debug 模式后，构建过程会输出：
+```tsx
+// ❌ SSR 时表达式字符串始终 truthy → 结构不匹配
+{showBanner && <Banner />}
 
-```
-vite-plugin-shopify:entries scanned 5 entries: {"section":3,"block":2}
-vite-plugin-shopify:ssg:compiler found 5 entries to compile
-vite-plugin-shopify:ssg:compiler entry counter has 1 CSS files
-vite-plugin-shopify:ssg:compiler entry hello-world has 1 CSS files
-vite-plugin-shopify:ssg:compiler generated shared CSS snippet react-css-SharedCard (used by 2 entries)
-vite-plugin-shopify:ssg:compiler compiling counter (type=section, css inline=0, css snippets=1)
-vite-plugin-shopify:ssg:compiler bundling counter via esbuild
-vite-plugin-shopify:ssg:compiler esbuild bundle took 53ms
-...
-[vite-plugin-shopify] Starting SSG compilation...
-[vite-plugin-shopify] Compiled 5 entries
-[vite-plugin-shopify] SSG compilation complete
+// ✅ DOM 结构不变，仅切换属性
+<section hidden={!parseLiquidBoolean(showBannerRaw)}>...</section>
 ```
 
-### 日志级别
+### inline style 颜色值
 
-| 级别 | 触发条件 | 可见性 |
-|------|----------|--------|
-| `info` | 始终可见 | 构建阶段摘要、完成计数 |
-| `warn` | 始终可见 | 缺少依赖、跳过的组件 |
-| `error` | 始终可见 | 编译失败的组件及堆栈 |
-| `debug` | 仅 debug 模式 | 入口扫描结果、CSS 分发、esbuild 耗时、配置详情 |
+**用 CSS 自定义属性代替内联颜色**：
 
-### 诊断场景
+```tsx
+// ❌ 浏览器规范化 hex → rgb → 不匹配
+<div style={{ backgroundColor: color }} />
 
-- **组件未被识别** → 开启 debug，检查 `scanned entries` 输出，确认文件和目录命名
-- **CSS 未生效** → 开启 debug，检查 `has CSS files` 和 `css inline/snippets` 统计
-- **SSG 渲染失败** → `error` 级别自动输出完整错误堆栈
-- **构建缓慢** → 开启 debug，检查每个组件的 `esbuild bundle took Xms`
+// ✅ CSS 变量不归一化
+<div style={{ "--accent": color } as React.CSSProperties} />
+// CSS: .accent { background-color: var(--accent); }
+```
 
 ---
 
 ## 注意事项
 
-1. **React / ReactDOM 不打包进 bundle**：通过 import map 从 CDN 加载，避免重复打包和体积膨胀
-2. **CSS Module hash 差异**：SSG 预渲染的 HTML 使用原始类名，水合后才会替换为 hash 类名。如需完美匹配，建议使用全局 CSS 而非 CSS Module，或接受短暂的样式跳跃
-3. **SSG 使用默认 props 渲染**：构建时的预渲染使用组件的默认 prop 值，编辑器中修改 setting 后会通过水合更新
-4. **Template 类型不包裹**：`type: "template"` 的组件 HTML 直接输出，不添加 section/block 外层结构，适用于整页模板
-5. **Section 必须有预设才能通过编辑器添加**：没有 `presets` 的 section 需要手动在 JSON 模板中引用，编辑器无法直接添加
-6. **`{% content_for 'blocks' %}` 自动插入**：当 `shopifyMeta.blocks` 非空时，插件自动在生成的 Liquid 中插入子 block 渲染标签
-7. **构建产物默认输出到 `assets/`**：如需与其他静态资源隔离，可设置 `buildDir: "assets/build"` 将产物输出到子目录，然后在 `.gitignore` 中添加 `assets/build/` 忽略该目录
-8. **Watch 模式自动关闭压缩**：`vite build --watch` 时自动设置 `minify: false` 并启用 inline sourcemap，方便在浏览器中调试。生产构建（`vite build`）则使用正常压缩
-9. **增量构建依赖 Rolldown 缓存**：watch 模式下 Rolldown 的 `ScanStageCache` 自动缓存模块图，文件变更时仅重新扫描变更模块，大幅加速构建。首次启动执行全量构建，后续为增量构建
+- **SSR 渲染生成 Liquid 模板**：构建时的 SSG 渲染将 settings/params 访问映射为 Liquid tag（如 `{{ section.settings.title }}`），由 Shopify 服务端解析为真实值
+- **Template 类型不包裹**：`type: "template"` 的 HTML 直接输出，不添加 section/block 外层结构
+- **Section 必须有预设才能通过编辑器添加**
+- **构建产物默认输出到 `assets/`**：可通过 `buildDir` 配置子目录
+- **Watch 模式**：`vite build --watch` 时自动关闭压缩并启用 inline sourcemap
+- **Settings 按需追踪**：SSR 阶段追踪组件 render body 中实际访问的 Liquid 表达式，只将访问过的表达式注入 `data-ssg-liquid` JSON bridge