开发环境搭建

在编写 Liquid 主题前，需要可重复的本地环境：Node（运行 Shopify CLI）、Git、编辑器与 Liquid 支持、Partner 店铺或开发店用于 shopify theme dev。本文按「安装 → 校验 → 目录约定 → 排错」组织，并与本专栏 Shopify CLI、工作流程 衔接。

你将完成什么

• 安装并校验 Node / npm 与 Shopify CLI
• 配置 VS Code（或同类编辑器）的 Liquid 与格式化
• 了解 Theme Check、推荐目录结构
• 能独立处理版本、权限、网络等常见阻塞

前置条件

系统与硬件建议

• 内存：8GB 及以上更顺畅（同时开浏览器预览 + 编辑器 + CLI）
• CPU：无硬性要求；大型主题 theme check 会占用一定 CPU

1. Node.js

Shopify CLI 依赖 Node。请使用当前 CLI 文档要求的 LTS 主版本（安装前可查看 Shopify CLI 安装说明 ）。

安装方式

官网安装包

• 下载：https://nodejs.org/ （选 LTS）

macOS（Homebrew）

brew install node
node --version
npm --version

Windows（Chocolatey）

choco install nodejs-lts

Linux（Debian/Ubuntu 示例）

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version

版本管理（推荐 nvm）

多项目并存时，用 nvm 切换 Node 版本：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install --lts
nvm use --lts

2. Git

主题仓库与 CLI 拉取推送均依赖 Git。

• 下载：https://git-scm.com/ 
• macOS：xcode-select --install 或 brew install git
• 初始化用户信息：

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

3. Shopify CLI

安装与登录流程见专文：Shopify CLI 使用指南。环境阶段只需验证：

npm install -g @shopify/cli @shopify/theme
shopify version
shopify auth login --store your-dev-store.myshopify.com

4. 编辑器（以 VS Code 为例）

推荐扩展

settings.json 片段

{
  "liquid.format.enable": true,
  "files.associations": {
    "*.liquid": "liquid"
  },
  "emmet.includeLanguages": {
    "liquid": "html"
  },
  "[liquid]": {
    "editor.defaultFormatter": "Shopify.theme-check-vscode"
  }
}

若团队使用 WebStorm / Cursor，请确保启用 Liquid 或 Shopify 相关插件，并统一 缩进（建议 2 空格） 与 换行符（LF），避免 CR 导致 CI 与 Theme Check 告警。

5. Theme Check（主题质量）

在 CI 或提交前运行 Theme Check，可提前发现弃用 API、错误 render 参数、缺失翻译键等问题。

shopify theme check

详细规则与忽略配置见官方：Theme Check 。本专栏 最佳实践 与 代码组织 中的约定应与规则集一致。

6. 浏览器

使用 Chrome 或 Edge（Chromium） 进行预览与 DevTools 性能分析（LCP、CLS）。移动端调试使用设备模拟或真实手机同一局域网预览（取决于 shopify theme dev 暴露的 URL）。

7. 环境自检脚本

mkdir -p shopify-dev-test && cd shopify-dev-test
npm init -y
node -e "console.log('Node', process.version)"

若 shopify version 与 node -e 均正常，即可进入 主题开发工作流程 拉取第一个主题。

8. 推荐目录结构

在机器上固定工作区，便于备份与多项目切换：

~/shopify-development/
├── themes/          # 各客户或内部主题 Git 仓库
├── apps/            # 如需配套自定义应用
├── tools/           # 脚本、主题检查配置共享
└── learning/        # 练习与 POC

创建示例：

mkdir -p ~/shopify-development/{themes,apps,tools,learning}

9. npm 镜像（可选）

中国大陆用户若安装 CLI 或依赖较慢，可临时使用镜像（注意公司安全策略）：

npm config set registry https://registry.npmmirror.com

恢复官方源：

npm config set registry https://registry.npmjs.org/

10. 故障排除

Node 版本过旧或过新

使用 nvm 切换到 CLI 文档推荐的 LTS，再执行 npm install -g @shopify/cli @shopify/theme。

Linux / macOS npm 权限错误

sudo chown -R "$(whoami)" ~/.npm
# 若曾用 sudo 全局安装，避免混用；可改为仅用户目录前缀或使用 nvm

无法访问 shopify.com

ping shopify.com
curl -I https://shopify.dev

若超时，检查 DNS、公司防火墙或合规代理；不要在文档示例中硬编码代理密钥。

下一步

1. Shopify CLI 使用指南 — 登录、拉主题、theme dev
2. 主题开发工作流程 — Git 分支与预览协作
3. Liquid 快速入门 — 开始写模板