Shopify CLI 安装与配置

Shopify CLI 是官方提供的命令行工具，用于加速 Shopify 主题和应用的开发。本指南将详细介绍如何安装、配置和使用 Shopify CLI。

什么是 Shopify CLI？

Shopify CLI 是一个命令行界面工具，提供以下功能：

主题开发: 创建、预览和部署主题
应用开发: 构建和测试 Shopify 应用
实时预览: 本地开发时实时预览更改
代码生成: 自动生成模板和组件
部署管理: 简化主题发布流程

安装前准备

确保您已经完成了开发环境搭建：

✅ Node.js (16.x 或更高版本)
✅ npm 或 yarn
✅ Git
✅ 代码编辑器

安装方法

方法一：使用 npm 安装 (推荐)

# 全局安装 Shopify CLI
npm install -g @shopify/cli @shopify/theme
 
# 验证安装
shopify version

方法二：使用 yarn 安装

# 全局安装
yarn global add @shopify/cli @shopify/theme
 
# 验证安装
shopify version

方法三：直接下载二进制文件

Windows

# 使用 PowerShell
iwr https://github.com/Shopify/shopify-cli/releases/latest/download/shopify-cli-windows-amd64.exe -OutFile shopify.exe
 
# 将 shopify.exe 移动到 PATH 中的目录

macOS

# 使用 Homebrew
brew tap shopify/shopify
brew install shopify-cli
 
# 或直接下载
curl -L https://github.com/Shopify/shopify-cli/releases/latest/download/shopify-cli-darwin-amd64 -o shopify
chmod +x shopify
sudo mv shopify /usr/local/bin/

Linux

# 下载并安装
curl -L https://github.com/Shopify/shopify-cli/releases/latest/download/shopify-cli-linux-amd64 -o shopify
chmod +x shopify
sudo mv shopify /usr/local/bin/

验证安装

# 检查版本
shopify version
 
# 查看帮助信息
shopify help
 
# 查看所有可用命令
shopify --help

身份验证

登录到 Shopify

# 登录到您的 Shopify 账户
shopify auth login
 
# 这将打开浏览器进行身份验证
# 按照屏幕提示完成登录过程

验证登录状态

# 检查当前登录状态
shopify auth whoami
 
# 查看可访问的商店
shopify auth list-stores

登出

# 登出当前账户
shopify auth logout

主题开发命令

创建新主题

# 创建基于 Dawn 的新主题
shopify theme init my-new-theme
 
# 进入主题目录
cd my-new-theme

连接现有主题

# 在现有主题目录中
shopify theme pull
 
# 或指定主题 ID
shopify theme pull --theme-id=123456789

本地开发服务器

# 启动开发服务器
shopify theme dev
 
# 指定商店
shopify theme dev --store=your-store.myshopify.com
 
# 使用特定主题
shopify theme dev --theme-id=123456789

开发服务器将在 http://localhost:9292 启动，提供：

🔄 热重载功能
📱 移动预览
🛠️ 开发工具集成

主题管理

# 查看商店中的所有主题
shopify theme list
 
# 推送本地更改到远程主题
shopify theme push
 
# 从远程拉取更改
shopify theme pull
 
# 发布主题
shopify theme publish --theme-id=123456789
 
# 创建主题副本
shopify theme duplicate --theme-id=123456789 --name="My Copy"

高级配置

配置文件

Shopify CLI 使用配置文件来存储设置：

# 查看配置文件位置
shopify config
 
# 编辑配置
shopify config edit

忽略文件配置

创建 .shopifyignore 文件来排除文件：

# .shopifyignore
node_modules/
.git/
*.log
.env
.DS_Store
thumbs.db

环境变量

# 设置默认商店
export SHOPIFY_FLAG_STORE="your-store.myshopify.com"
 
# 设置主题 ID
export SHOPIFY_FLAG_THEME_ID="123456789"
 
# 启用调试模式
export SHOPIFY_CLI_DEBUG=1

代码生成功能

生成 Section

# 生成新的 section
shopify theme generate section
 
# 或指定名称
shopify theme generate section hero-banner

生成 Snippet

# 生成 snippet
shopify theme generate snippet
 
# 指定名称
shopify theme generate snippet product-card

生成模板

# 生成页面模板
shopify theme generate template page
 
# 生成产品模板
shopify theme generate template product

工作流程示例

日常开发流程

# 1. 拉取最新代码
shopify theme pull
 
# 2. 启动开发服务器
shopify theme dev
 
# 3. 在另一个终端进行开发
# 编辑文件，浏览器会自动刷新
 
# 4. 提交更改
git add .
git commit -m "Add new feature"
 
# 5. 推送到远程主题
shopify theme push
 
# 6. 如果准备发布
shopify theme publish

团队协作流程

# 创建开发分支
git checkout -b feature/new-homepage
 
# 创建开发主题
shopify theme push --unpublished --json > theme-info.json
 
# 获取主题 ID
cat theme-info.json | jq -r '.theme.id'
 
# 在特定主题上开发
shopify theme dev --theme-id=THEME_ID
 
# 完成开发后合并代码
git checkout main
git merge feature/new-homepage
 
# 推送到主主题
shopify theme push --theme-id=MAIN_THEME_ID

故障排除

常见问题

1. 认证问题

# 清除认证缓存
shopify auth logout
shopify auth login
 
# 检查网络连接
ping shopify.com

2. 权限问题

# 检查商店权限
shopify auth whoami
 
# 确保拥有主题编辑权限
# 联系商店所有者分配权限

3. 版本冲突

# 更新到最新版本
npm update -g @shopify/cli @shopify/theme
 
# 清除 npm 缓存
npm cache clean --force

4. 端口冲突

# 指定不同端口
shopify theme dev --port=3000
 
# 查看端口使用情况
netstat -tulpn | grep :9292

调试技巧

# 启用详细日志
shopify theme dev --verbose
 
# 查看详细错误信息
SHOPIFY_CLI_DEBUG=1 shopify theme dev
 
# 检查主题文件
shopify theme check

最佳实践

1. 版本控制集成

# .gitignore
.shopify/
*.log
.env
node_modules/

2. 自动化脚本

// package.json
{
  "scripts": {
    "dev": "shopify theme dev",
    "push": "shopify theme push",
    "pull": "shopify theme pull",
    "check": "shopify theme check",
    "build": "npm run check && npm run push"
  }
}

3. CI/CD 集成

# .github/workflows/deploy.yml
name: Deploy Theme
on:
  push:
    branches: [main]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '16'
      
      - name: Install Shopify CLI
        run: npm install -g @shopify/cli @shopify/theme
        
      - name: Deploy to Shopify
        env:
          SHOPIFY_CLI_TOKEN: ${{ secrets.SHOPIFY_CLI_TOKEN }}
          SHOPIFY_FLAG_STORE: ${{ secrets.SHOPIFY_STORE }}
        run: shopify theme push --allow-live

高级功能

主题检查

# 运行主题检查
shopify theme check
 
# 只检查特定文件
shopify theme check templates/
 
# 生成报告
shopify theme check --output=json > check-report.json

性能分析

# 分析主题性能
shopify theme dev --timing
 
# 查看文件大小
shopify theme info

多环境管理

# 开发环境
shopify theme dev --store=dev-store.myshopify.com
 
# 测试环境  
shopify theme push --store=staging-store.myshopify.com
 
# 生产环境
shopify theme push --store=production-store.myshopify.com --live