Git版本控制最佳实践

先判断问题出现在哪里

在没有 Git 的时代，Shopify 主题开发就像是在走钢丝：改错一行代码，只能靠 Ctrl+Z 疯狂撤销，一旦关闭编辑器，代码就永远找不回来了。

核心逻辑是：代码资产化与部署自动化 (CI/CD)。

通过引入 Git 版本控制，每一次修改都有迹可循。更重要的是，Shopify 官方现已深度集成 GitHub。你可以将 GitHub 仓库的 main 分支直接绑定到 Shopify 的 Live 主题。当你在本地 git push 时，Shopify 会自动拉取最新代码并上线，彻底告别手动上传 ZIP 包的原始时代。

实战步骤

步骤 1：初始化 Git 仓库与 `.gitignore`

操作路径：本地项目根目录终端

运行 git init 初始化仓库。

极其重要：创建 .gitignore 文件。必须忽略以下文件，否则会导致严重冲突：

node_modules/
.env
config/settings_data.json  # 忽略云端配置，防止覆盖商家在后台的修改
templates//*.json        # 忽略 JSON 模板，原因同上

注意：如果你是开发一个全新的主题准备出售，你需要提交默认的 settings_data.json。但如果是为现有商家定制主题，绝对不能把本地空的 JSON 配置文件 push 到线上，这会清空商家的所有排版数据！

步骤 2：建立标准的分支管理模型 (Git Flow)

操作路径：Git 命令行或可视化工具

main 分支：永远对应线上正在营业的 Live 主题。绝对不能直接在 main 分支上写代码。
staging 分支：测试分支。对应 Shopify 后台的一个未发布主题（如 "Staging Theme"），用于 QA 测试。
feature/xxx 分支：功能分支。例如你要开发一个新的倒计时区块，创建一个 feature/countdown-timer 分支，开发完成后合并到 staging，测试无误后再合并到 main。

步骤 3：配置 Shopify GitHub 集成

操作路径：Shopify后台 -> 在线商店 -> 模板 -> 添加模板 -> 从 GitHub 连接

授权 Shopify 访问你的 GitHub 账号。
选择你的主题仓库。
绑定分支：
- 将仓库的 main 分支连接到一个名为 "Production (Auto-sync)" 的主题。
- 将仓库的 staging 分支连接到一个名为 "Staging (QA)" 的主题。
连接成功后，只要 GitHub 上的分支发生更新，Shopify 会在几秒钟内自动同步代码。

步骤 4：处理商家在后台的修改 (双向同步)

操作路径：Shopify后台与 GitHub 之间的自动提交

这是 Shopify GitHub 集成最强大的地方。
如果商家在 Shopify 后台的编辑器里修改了文案，或者添加了一个 Section，Shopify 会自动在你的 GitHub 仓库中生成一个 Commit（提交者显示为 Shopify）。
前端开发者在本地写代码前，只需运行 git pull origin main，就能将商家在后台的修改同步到本地，彻底解决了代码冲突问题。

常见误区与处理方法

误区一：将包含敏感 API 密钥的 `.env` 文件提交到公共仓库

规避方法：在现代前端开发中，我们经常使用 .env 文件来存储第三方接口的 API 密钥（如 Klaviyo 私钥、自定义 App 的 Token）。如果你在 git add . 之前忘记配置 .gitignore，这些密钥会被直接推送到 GitHub。如果是公开仓库，黑客会在 5 分钟内扫描到这些密钥并盗用你的账户。第一准则：.env 必须第一时间加入 .gitignore。线上所需的密钥应该通过 Shopify 后台的 Theme Settings 或 Metafields 进行安全配置。

误区二：强行覆盖商家在后台修改的 JSON 模板

规避方法：这是新手最容易犯的灾难性错误！你在本地修改了 templates/index.json（比如加了一个测试区块），然后 git push 到了 main 分支。由于 GitHub 集成的自动同步，这会直接覆盖线上 index.json。结果商家昨天在首页辛辛苦苦排版了 3 个小时的商品列表和 Banner 图，瞬间全部消失！在为现有店铺开发时，除非你需要新增一个全新的页面模板，否则绝对不要将本地的 templates/*.json 和 config/settings_data.json 提交到 Git 仓库。将它们加入 .gitignore，让商家在后台掌控排版数据，开发者只负责提供代码组件（Sections/Snippets）。

误区三：在 Shopify 后台直接编辑已绑定 GitHub 的主题代码

规避方法：虽然 Shopify 允许你在后台的“编辑代码（Edit Code）”界面直接修改文件，但如果你修改的是一个已经绑定了 GitHub 分支的主题，这会触发一个自动的 Git Commit 推送到你的仓库。如果此时你本地也有未提交的修改，下次 git pull 时会产生极其复杂的合并冲突（Merge Conflict）。一旦主题绑定了 GitHub，必须确立铁律：所有的代码修改（Liquid, JS, CSS）只能在本地 IDE 中进行并通过 Git 推送。严禁任何人（包括商家）在 Shopify 后台直接修改代码文件。

FAQ