Shopify Dawn主题如何通过File Transformation自定义文件结构？

核心问题结论 #

• 完全可以通过Shopify的JIT文件转换功能实现高可维护的自定义文件结构，不需要死守Dawn默认的扁平目录规则
• 原生支持按功能模块归类的组件化开发模式，HTML/Liquid、CSS、JS文件可以按模块放在同一个目录下管理，和你熟悉的Angular组件组织逻辑非常接近

实现原理 #

这个功能的本质是Shopify CLI在本地预览、推送主题上线时，会按照你在配置文件里写好的规则，自动把你本地自定义目录下的文件映射、复制到Shopify主题要求的标准目录结构中，整个过程不会改动你本地仓库的文件组织方式，也不需要你手动整理文件到对应目录。

你完全可以按照前端组件化的习惯搭建本地目录结构，参考结构如下：

your-theme/
├── src/
│   ├── components/ # 通用组件目录
│   │   ├── product-card/ # 单个组件独立文件夹
│   │   │   ├── product-card.liquid  # 组件模板
│   │   │   ├── product-card.css     # 组件私有样式
│   │   │   └── product-card.js      # 组件交互逻辑
│   │   ├── cart-drawer/
│   │   │   ├── cart-drawer.liquid
│   │   │   ├── cart-drawer.css
│   │   │   └── cart-drawer.js
│   ├── sections/   # 页面级section
│   ├── snippets/   # 全局复用片段
│   ├── assets/
│   │   ├── global/ # 全局样式、公共脚本
│   │   └── images/ # 图片、SVG等静态资源
│   └── layout/     # 全局布局文件
└── shopify.theme.toml # JIT转换规则配置文件

转换规则直接写在shopify.theme.toml里即可，参考配置：

[file_transformations]
  [file_transformations.jit]
    # 组件文件映射规则
    "src/components/*/*.liquid" = "snippets/{{file_name}}.liquid"
    "src/components/*/*.css" = "assets/{{file_name}}.css"
    "src/components/*/*.js" = "assets/{{file_name}}.js"
    # 静态资源映射规则
    "src/assets/images/*" = "assets/{{file_name}}.{{extension}}"
    "src/assets/global/*.css" = "assets/{{file_name}}.css"
    # 主题核心文件映射规则
    "src/layout/*.liquid" = "layout/{{file_name}}.liquid"
    "src/sections/*.liquid" = "sections/{{file_name}}.liquid"

实操踩坑注意事项 #

• 所有资源文件必须全局唯一命名：因为转换后CSS、JS、图片最终都会落到Shopify要求的扁平assets目录，如果你两个不同组件下都有叫style.css的文件，转换时会直接覆盖，排查问题非常麻烦。就按Angular组件的命名习惯，文件名和组件名保持一致即可，不要用index.css main.js这类通用名。
• 模板内的资源引用路径要写转换后的最终路径：比如在Liquid里引入组件样式，还是要写{{ 'product-card.css' | asset_url | stylesheet_tag }}，不要写本地的src/components/product-card/product-card.css路径，线上Shopify服务器只识别转换后的标准结构。
• 这个功能只做路径映射，不做编译构建：目前JIT转换不支持Sass/Less编译、TS转译、JS打包压缩这类操作，如果你要用到预处理器或者模块化JS能力，还是要在外面套一层Vite/Webpack之类的构建工具，把构建产物输出到约定的src目录，再走Shopify的JIT转换流程。
• 本地开发必须用3.0及以上版本的Shopify CLI：旧版CLI不识别JIT转换配置，推送主题时会把你整个自定义目录原样上传，直接导致线上主题报错。
• 不要把需要后台在线编辑的文件放到自定义转换目录：Shopify后台的在线代码编辑器只能识别标准主题结构下的文件，放在自定义目录里的源文件后台看不到，运营人员在线编辑的内容也不会同步回你的本地源文件。

内容的提问来源于stack exchange，提问作者Miguel Pájaro