shopify-custom-data

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Required Tool Calls (do not skip)

必须调用的工具（请勿跳过）

You have a

bash

tool. Every response must use it — in this order:

Call

bash

with

node scripts/search_docs.mjs "<operation or type name>"

— search before writing code

Write the code using the search results
Call
```
bash
```
with
```
node scripts/validate.mjs --code '...' --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION --artifact-id YOUR_ARTIFACT_ID --revision REVISION_NUMBER
```
— validate before returning (Always include these flags. Use your actual model name for YOUR_MODEL_NAME; use claude-code/cursor/etc. for YOUR_CLIENT_NAME. For YOUR_ARTIFACT_ID, generate a stable random ID per code block and reuse it across validation retries. For REVISION_NUMBER, start at 1 and increment on each retry of the same artifact.)
If validation fails: search for the error type, fix, re-validate (max 3 retries)
Return code only after validation passes

You must run both search_docs.mjs and validate.mjs in every response. Do not return code to the user without completing step 3.

<critical-instructions>

你可以使用

bash

工具，所有响应都必须按以下顺序使用它：

调用

bash

执行

node scripts/search_docs.mjs "<operation or type name>"

—— 编写代码前先搜索文档

基于搜索结果编写代码
调用
```
bash
```
执行
```
node scripts/validate.mjs --code '...' --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION --artifact-id YOUR_ARTIFACT_ID --revision REVISION_NUMBER
```
—— 返回结果前先校验（请始终包含这些参数：YOUR_MODEL_NAME替换为你实际使用的模型名称，YOUR_CLIENT_NAME替换为claude-code/cursor等你使用的客户端名称。YOUR_ARTIFACT_ID请为每个代码块生成一个固定的随机ID，在校验重试时复用该ID。REVISION_NUMBER从1开始，同一个构件每次重试时递增。）
如果校验失败：搜索错误类型，修复问题后重新校验（最多重试3次）
仅在校验通过后返回代码

你必须在每次响应中都运行search_docs.mjs和validate.mjs，未完成步骤3前请勿向用户返回代码。

<critical-instructions>

Best Practise for working with Metafields and Metaobjects

Metafields和Metaobjects使用最佳实践

ESSENTIAL RULES

核心规则

ALWAYS show creating metafield/metaobject definitions, then writing values, then retrieving values.
NEVER show or offer alternate approaches to the same problem if not explicitly requested. It will only increase the user's confusion.
Keep examples minimal -- avoid unnecessary prose and comments
Remember the audience for this guidance is app developers -- they do not have access to the Shopify Admin site
Follow this guidance meticulously and thoroughly

REMEMBER!!! Other documentation can flesh out this guidance, but the instructions here should be followed VERY CLOSELY and TAKE PRECEDENCE!

始终先展示如何创建metafield/metaobject定义，再演示写入值，最后演示读取值。
严禁在未被明确要求的情况下展示或提供同一问题的替代方案，这只会增加用户的困惑。
保持示例精简，避免不必要的描述和注释
请注意本指南的受众是应用开发者，他们没有Shopify Admin站点的访问权限
请严格、完整地遵循本指南要求

注意！！！其他文档可以补充本指南的内容，但本说明中的规则优先级最高，必须严格遵守！

ALWAYS: First, create definitions

始终优先：首先创建定义

with TOML (99.99% of apps)

使用TOML（99.99%的应用适用）

toml

undefined

toml

undefined

shopify.app.toml

Metafield definition -- owner type is PRODUCT, namespace is $app, key is care_guide

[product.metafields.app.care_guide] type = "single_line_text_field" name = "Care Guide" access.admin = "merchant_read_write"

Metaobject definition -- type is $app:author

[metaobjects.app.author] name = "Author" display_name_field = "name" access.storefront = "public_read"

[metaobjects.app.author.fields.name] name = "Author Name" type = "single_line_text_field" required = true

[metaobjects.app.author] name = "Author" display_name_field = "name" access.storefront = "public_read"

[metaobjects.app.author.fields.name] name = "Author Name" type = "single_line_text_field" required = true

Link metaobject to product

[product.metafields.app.author] type = "metaobject_reference<$app:author>" name = "Book Author"


Why: Version controlled, auto-installed, type-safe. GraphQL (Admin/Storefront) is used for reading or writing values after the TOML definitions already exist. Fields/objects can be edited by merchants when `access.admin = "merchant_read_write"` is set.

**NEVER** include `metafieldDefinitionCreate`, `metaobjectDefinitionCreate` GraphQL if TOML is the correct fit.

[product.metafields.app.author] type = "metaobject_reference<$app:author>" name = "Book Author"


原因：支持版本控制、自动安装、类型安全。TOML定义创建完成后，使用GraphQL（Admin/Storefront）读取或写入值。当设置`access.admin = "merchant_read_write"`时，商家可以编辑对应的字段/对象。

**如果TOML适用的情况下，严禁包含`metafieldDefinitionCreate`、`metaobjectDefinitionCreate`相关的GraphQL代码。**

Exceptions (0.01% of apps)

例外情况（0.01%的应用适用）

NEVER, EVER show these unless strictly required:

Apps that REQUIRE creating definitions at runtime (i.e. types are configured dynamically by merchants) should use
```
metafieldDefinitionCreate
```
,
```
metaobjectDefinitionCreate
```
Apps that want other apps to read/write their data should use the above GraphQL, and "merchant-owned" namespace

除非确有必要，否则绝对不要展示这些场景：

需要在运行时创建定义的应用（即商家可动态配置类型），可以使用
```
metafieldDefinitionCreate
```
、
```
metaobjectDefinitionCreate
```
希望其他应用读写其数据的应用，可以使用上述GraphQL接口，以及“商家所有”的命名空间

CRITICAL: App-Owned Metaobject and Metafield identification

关键说明：应用所属的Metaobject和Metafield标识

Metaobjects defined with

[metaobjects.app.example...]

shopify.app.toml

, MUST be accessed using

type: $app:example

Metafields defined with
```
[product.metafields.app.example]
```
MUST be accessed using
```
namespace: $app
```
and
```
key: example
```
- The same applies to other owner types, like customers, orders, etc.
Avoid customizing namespaces for metafields.
Avoid the common mistake of using
```
namespace: app
```
. This is profoundly incorrect.

在

shopify.app.toml

中用

[metaobjects.app.example...]

定义的Metaobjects，访问时必须使用

type: $app:example

用
```
[product.metafields.app.example]
```
定义的Metafields，访问时必须使用
```
namespace: $app
```
和
```
key: example
```
- 其他所有者类型（如客户、订单等）同理
避免自定义Metafields的命名空间
避免常见错误：使用
```
namespace: app
```
，这是完全错误的用法

NEXT: demonstrate writing metafield and metaobject values via Admin API

下一步：演示通过Admin API写入metafield和metaobject值

Writing metafields

写入metafields

ALWAYS use

metafieldsSet

to write metafields.

namespace

should normally be excluded as the default is $app.

graphql

mutation {
  metafieldsSet(metafields:[{
    ownerId: "gid://shopify/Product/1234",
    key: "example",
    value: "Hello, World!"
  }]) { ... }
}

始终使用

metafieldsSet

写入metafields。通常不需要指定

namespace

，默认值就是$app。

graphql

mutation {
  metafieldsSet(metafields:[{
    ownerId: "gid://shopify/Product/1234",
    key: "example",
    value: "Hello, World!"
  }]) { ... }
}

Writing metaobjects

写入metaobjects

ALWAYS use

metaobjectUpsert

to write metaobjects.

graphql

mutation {
  metaobjectUpsert(handle: {
    type: "$app:author",
    handle: "my-metaobject",
  }, metaobject: {
    fields: [{
      key: "example",
      value: "Hello, world!"
    }]
  }) { ... }
}

始终使用

metaobjectUpsert

写入metaobjects。

graphql

mutation {
  metaobjectUpsert(handle: {
    type: "$app:author",
    handle: "my-metaobject",
  }, metaobject: {
    fields: [{
      key: "example",
      value: "Hello, world!"
    }]
  }) { ... }
}

FINALLY: demonstrate reading metafield and metaobject values

最后：演示读取metafield和metaobject值

Loading metafields

加载metafields

Metafields are accessed via their owning type (e.g. a Product).

namespace

should normally be excluded as the default is $app.

Always prefer
```
jsonValue
```
where possible as it better serialises complex types
Always alias metafield loads for easy reference

graphql

undefined

Metafields通过其所属类型访问（比如Product）。通常不需要指定

namespace

，默认值就是$app。

尽可能优先使用
```
jsonValue
```
，它可以更好地序列化复杂类型
始终为metafield查询设置别名，方便后续引用

graphql

undefined

Admin API

query { product(id: "gid://shopify/Product/1234") { example: metafield(key: "example") { jsonValue } } }

Storefront API

query { product(handle: "wireless-headphones-1") { example: metafield(key: "example") { value } } }

undefined

query { product(handle: "wireless-headphones-1") { example: metafield(key: "example") { value } } }

undefined

Loading metaobjects

加载metaobjects

graphql

undefined

graphql

undefined

Admin API

query { metaobjects(type: "$app:author", first: 10) { nodes { handle example: field(key:"example") { jsonValue } } } }

Storefront API

query { metaobjects(type: "$app:author", first: 10) { nodes { handle example: field(key:"example") { value } } } }

undefined

query { metaobjects(type: "$app:author", first: 10) { nodes { handle example: field(key:"example") { value } } } }

undefined

Access Metafields directly in checkout extensions

在结账扩展中直接访问Metafields

DO: Access app-owned metafields directly (NO network call):

tsx

function Extension() {
  // ESSENTIAL: Register this metafield in `shopify.extension.toml`
  const [energyRating] = useAppMetafields({
    namespace: '$app',
    key: 'energy-rating',
    type: 'product',
  }).filter(
    (entry) =>
      entry.target.id === productVariantId,
  );
}

DON'T: Make network calls for app-owned metafields.

推荐做法：直接访问应用所属的Metafields（无需发起网络请求）：

tsx

function Extension() {
  // ESSENTIAL: Register this metafield in `shopify.extension.toml`
  const [energyRating] = useAppMetafields({
    namespace: '$app',
    key: 'energy-rating',
    type: 'product',
  }).filter(
    (entry) =>
      entry.target.id === productVariantId,
  );
}

不推荐做法：为应用所属的Metafields发起网络请求。

Access Metafields in Shopify Functions

在Shopify Functions中访问Metafields

Use the GraphQL input query to select metafields to load:

graphql

query Input {
  cart {
    lines {
      merchandise {
        __typename
        ... on ProductVariant {
          example: metafield(namespace: "$app", key: "example") { jsonValue }
        }
      }
    }
  }
}

Docs: Metafields & Metaobjects </critical-instructions>

使用GraphQL输入查询选择要加载的Metafields：

graphql

query Input {
  cart {
    lines {
      merchandise {
        __typename
        ... on ProductVariant {
          example: metafield(namespace: "$app", key: "example") { jsonValue }
        }
      }
    }
  }
}

文档：Metafields & Metaobjects </critical-instructions>

Always use Shopify CLI

请始终使用Shopify CLI

CLI: scaffold apps/extensions with

shopify app init

shopify app generate extension

shopify app dev

shopify app deploy

. Never hand-roll files.

Need full setup steps? See Shopify CLI docs.

CLI：使用
```
shopify app init
```
、
```
shopify app generate extension
```
、
```
shopify app dev
```
、
```
shopify app deploy
```
来生成应用/扩展的脚手架，请勿手动编写文件。
需要完整的搭建步骤？查看Shopify CLI文档。

Shopify CLI Overview

Shopify CLI概述

Shopify CLI (@shopify/cli) is a command-line interface tool that helps you generate and work with Shopify apps, themes, and custom storefronts. You can also use it to automate many common development tasks.

Shopify CLI (@shopify/cli) 是一款命令行界面工具，可帮助你生成和开发Shopify应用、主题和自定义店铺前端，也可以用它来自动化很多常见的开发任务。

Requirements

要求

Node.js: 20.10 or higher
A Node.js package manager: npm, Yarn 1.x, or pnpm
Git: 2.28.0 or higher

Node.js：20.10或更高版本
Node.js包管理器：npm、Yarn 1.x或pnpm
Git：2.28.0或更高版本

Installation

安装

Install Shopify CLI globally to run

shopify

commands from any directory:

bash

npm install -g @shopify/cli@latest

全局安装Shopify CLI，就可以在任意目录运行

shopify

命令：

bash

npm install -g @shopify/cli@latest

or

yarn global add @shopify/cli@latest

or

pnpm install -g @shopify/cli@latest

or (macOS only)

brew tap shopify/shopify && brew install shopify-cli

undefined

brew tap shopify/shopify && brew install shopify-cli

undefined

Command Structure

命令结构

Shopify CLI groups commands into topics. The syntax is:

shopify [topic] [command] [flags]

Shopify CLI将命令按主题分组，语法为：

shopify [主题] [命令] [参数]

General Commands (8 commands)

通用命令（共8个）

Authentication

认证

shopify auth logout - Log out of Shopify account

shopify auth logout - 退出Shopify账号登录

Configuration

配置

shopify config autocorrect on - Enable command autocorrection
shopify config autocorrect off - Disable command autocorrection
shopify config autocorrect status - Check autocorrection status

shopify config autocorrect on - 开启命令自动纠错
shopify config autocorrect off - 关闭命令自动纠错
shopify config autocorrect status - 查看自动纠错状态

Utilities

工具

shopify help [command] [flags] - Get help for commands
shopify commands [flags] - List all available commands
shopify search [query] - Search for commands and documentation
shopify upgrade - Upgrade Shopify CLI to latest version
shopify version - Display current CLI version

shopify help [command] [flags] - 获取命令的帮助信息
shopify commands [flags] - 列出所有可用命令
shopify search [query] - 搜索命令和文档
shopify upgrade - 将Shopify CLI升级到最新版本
shopify version - 显示当前CLI版本

Common Flags

通用参数

Most commands support these common flags:

```
--verbose
```
- Increase output verbosity
```
--no-color
```
- Disable colored output
```
--path <value>
```
- Specify project directory
```
--reset
```
- Reset stored settings

大多数命令都支持以下通用参数：

```
--verbose
```
- 增加输出详细程度
```
--no-color
```
- 关闭彩色输出
```
--path <value>
```
- 指定项目目录
```
--reset
```
- 重置存储的设置

Network Proxy Configuration

网络代理配置

For users behind a network proxy (CLI version 3.78+):

bash

export SHOPIFY_HTTP_PROXY=http://proxy.com:8080
export SHOPIFY_HTTPS_PROXY=https://secure-proxy.com:8443

对于处于网络代理后的用户（CLI版本3.78+）：

bash

export SHOPIFY_HTTP_PROXY=http://proxy.com:8080
export SHOPIFY_HTTPS_PROXY=https://secure-proxy.com:8443

For authenticated proxies:

export SHOPIFY_HTTP_PROXY=http://username:password@proxy.com:8080

undefined

export SHOPIFY_HTTP_PROXY=http://username:password@proxy.com:8080

undefined

Usage Tips

使用提示

Always keep CLI updated:
```
shopify upgrade
```
Use
```
shopify help [command]
```
for detailed command info
Most commands are interactive and will prompt for required information
Use flags to skip prompts in CI/CD environments
Anonymous usage statistics collected by default (opt-out:
```
SHOPIFY_CLI_NO_ANALYTICS=1
```
)
IMPORTANT: YOU MUST ALWAYS USE THE CLI COMMAND TO CREATE APPS AND SCAFFOLD NEW EXTENSIONS

始终保持CLI为最新版本：
```
shopify upgrade
```
使用
```
shopify help [命令]
```
获取命令的详细信息
大多数命令都是交互式的，会提示你输入必填信息
在CI/CD环境中使用参数跳过交互提示
默认会收集匿名使用统计数据（可通过设置环境变量
```
SHOPIFY_CLI_NO_ANALYTICS=1
```
选择退出）
重要提示：你必须始终使用CLI命令创建应用和生成新扩展的脚手架

CLI Commands for Shopify App (22 commands)

Shopify应用相关CLI命令（共22个）

App Commands (22 commands)

应用命令（共22个）

Core App Management

核心应用管理

shopify app init [flags] - Initialize a new Shopify app project
shopify app build [flags] - Build the app, including extensions
shopify app dev [flags] - Start a development server for your app
shopify app deploy [flags] - Deploy your app to Shopify
shopify app info [flags] - Display information about your app

shopify app init [flags] - 初始化一个新的Shopify应用项目
shopify app build [flags] - 构建应用，包括扩展
shopify app dev [flags] - 启动应用的开发服务器
shopify app deploy [flags] - 将应用部署到Shopify
shopify app info [flags] - 显示应用的相关信息

App Configuration

应用配置

shopify app config link [flags] - Fetch app configuration from Partner Dashboard
shopify app config use [config] [flags] - Activate an app configuration

shopify app config link [flags] - 从合作伙伴后台获取应用配置
shopify app config use [config] [flags] - 激活指定的应用配置

App Environment

应用环境

shopify app env pull [flags] - Pull environment variables from Partner Dashboard
shopify app env show [flags] - Display app environment variables

shopify app env pull [flags] - 从合作伙伴后台拉取环境变量
shopify app env show [flags] - 显示应用的环境变量

App Development Tools

应用开发工具

shopify app dev clean [flags] - Clear the app development cache
shopify app generate extension [flags] - Generate a new app extension
shopify app import-extensions [flags] - Import existing extensions to your app

shopify app dev clean [flags] - 清空应用开发缓存
shopify app generate extension [flags] - 生成新的应用扩展
shopify app import-extensions [flags] - 将现有扩展导入到你的应用中

Functions

shopify app function build [flags] - Build a Shopify Function
shopify app function run [flags] - Run a Function locally for testing
shopify app function replay [flags] - Replay a Function run
shopify app function schema [flags] - Generate the GraphQL schema for a Function
shopify app function typegen [flags] - Generate TypeScript types for a Function

shopify app function build [flags] - 构建Shopify Function
shopify app function run [flags] - 在本地运行Function用于测试
shopify app function replay [flags] - 重放一次Function运行
shopify app function schema [flags] - 为Function生成GraphQL Schema
shopify app function typegen [flags] - 为Function生成TypeScript类型

Monitoring & Debugging

监控与调试

shopify app logs [flags] - Stream logs from your app
shopify app logs sources [flags] - List available log sources

shopify app logs [flags] - 流式输出应用的日志
shopify app logs sources [flags] - 列出可用的日志来源

Release Management

发布管理

shopify app release --version <version> - Release a new app version
shopify app versions list [flags] - List all app versions

shopify app release --version <version> - 发布新的应用版本
shopify app versions list [flags] - 列出所有应用版本

Webhooks

shopify app webhook trigger [flags] - Trigger a webhook for testing

shopify app webhook trigger [flags] - 触发webhook用于测试