# @getverdict/mock-bridge 中文文档

规范地址：https://npmcn.com/package/%40getverdict/mock-bridge/

版本：1\.3\.0
npm 元数据更新时间：2026-03-02T19:39:25.411Z
中文译文更新时间：2026-11-16T06:57:34.040Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40getverdict/mock-bridge
原文对照：https://npmcn.com/package/%40getverdict/mock-bridge/?lang=original
项目主页：https://github.com/ctrlaltdylan/mock-bridge#readme
源码仓库：https://github.com/ctrlaltdylan/mock-bridge

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：838 kB，59 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：8 个
- 首次发布：2025-10-14T17:27:36.427Z
- 最新版本发布：2026-03-02T19:39:25.297Z
- 近 30 天下载量：15364（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 3 个）

## 中文简介

用于测试和开发的Mock Shopify App桥

## 安装

```sh
npm install @getverdict/mock-bridge
```

也可以使用：`pnpm add @getverdict/mock-bridge`、`yarn add @getverdict/mock-bridge`、`bun add @getverdict/mock-bridge`

## README

![Mock Bridge Logo](https://npmcn.com/package/%40getverdict/mock-bridge/assets/img/mock-bridge-logo.png)

# 商店雾桥

Shopify嵌入式应用程序的综合浏览器测试解决方案. 在本地移动商店管理环境和App Bridge API,不需要真正的商店证书、卡布特查或2FA.

[![npm version](https://badge.fury.io/js/@getverdict%2Fmock-bridge.svg)](https://www.npmjs.com/package/@getverdict/mock-bridge) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🎥见于行

[![Mock Bridge Demo Video](https://npmcn.com/package/%40getverdict/mock-bridge/assets/img/yt-thumbnail.png)](https://www.youtube.com/watch?v=swflaGObK4A)

**[\* 观看演示视频](https://www.youtube.com/watch?v=swflaGObK4A)** - 看Moc Bridge如何简化商店应用测试

## 为什么使用这个软件包?

**测试 Shopify 嵌入式应用程序难度 :**

-   {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}店员需要2FA和Captchas
-   QQ Playwright/ 自定义工具无法绕过安全
-   Chrome DevTools MCP 无法与您的嵌入式 Shopify 应用程序交互
-   CI/CD管道需要互联网和证书
-   实际管理员的手工测试缓慢且不可靠

**这个软件包可以解决所有问题:**

-   \* 不需要卡布查、2FA或真正的Shopify账户
-   QQ 完全 Playwright 和自动化支持
-   QQ Chrome MCP 和 DevTools 兼容性
-   离线工程和CI/CD管道
-   \* 进行综合测试的真正数据库集成

## API 支持

### 核心特征

| 特性 | 状态 | 页:1 |
| --- | --- | --- |
| iFrame 嵌入 | 获支持 | 带有 Polaris 样式的完整管理框架 |
| 会话符号 | 获支持 | `shopify.idToken()` |
| 模拟环境探测 | 获支持 | 自动装入模拟 App 桥 |

### 应用桥 API

| API 密码 | 状态 | 页:1 |
| --- | --- | --- |
| `shopify.modal` | 获支持 | `show()`, (中文(简体) ), `hide()`, (中文(简体) ), `toggle()` |
| `shopify.saveBar` | 获支持 | `show()`, (中文(简体) ), `hide()`, (中文(简体) ), `toggle()` |
| `shopify.loading` | 获支持 | `loading(boolean)` |
| `shopify.toast` | 获支持 | `show(message, options)` |
| `shopify.idToken` | 获支持 | 返回有效的 JWT |
| `shopify.config` | 获支持 | `apiKey`, (中文(简体) ), `shop`, (中文(简体) ), `locale` |
| `shopify.environment` | 获支持 | `embedded`, (中文(简体) ), `mobile`, (中文(简体) ), `pos` |
| `shopify.user` | 获支持 | 返回模拟用户对象 |
| `shopify.scopes` | 🔶 Stu | 返回模拟数据 |
| `shopify.resourcePicker` | 🔶 Stu | 返回空数组 |
| `shopify.picker` | 🔶 Stu | 返回空选择 |
| `shopify.scanner` | 🔶 Stu | 返回模拟扫描数据 |
| `shopify.pos` | 🔶 Stu | 有模拟数据的 Cart API |
| `shopify.intents` | 🔶 Stu | `invoke()`, (中文(简体) ), `register()` |
| `shopify.webVitals` | 🔶 Stu | 只召回注册 |
| `shopify.support` | 🔶 Stu | 只召回注册 |
| `shopify.reviews` | 🔶 Stu | 回归成功 |
| `shopify.app` | 🔶 Stu | 返回空扩展 |
| 经认证的获取 | 获支持 | 模拟、代理或直接模式 |
| 导航 | 未执行 |  |
| 打印 | 未执行 |  |
| 份额 | 未执行 |  |

### Web 组件

| 构成部分 | 状态 | 页:1 |
| --- | --- | --- |
| `<ui-modal>` | 获支持 | 与 `<ui-title-bar>` 支助 |
| `<ui-save-bar>` | 获支持 | 与 `data-save-bar` 窗体整合 |
| `<ui-nav-menu>` | 获支持 | 在管理边栏显示 |
| `<ui-title-bar>` | 获支持 | 内部模式 |
| `<s-app-window>` | 未执行 |  |

**图例:** QQ 支持的 Stub (返回模拟数据) QQ 未执行

## \* 安装

```bash
npm install @getverdict/mock-bridge --save-dev
# or
yarn add @getverdict/mock-bridge --dev
# or
pnpm add @getverdict/mock-bridge --save-dev
```

## QQ 快速启动(2个命令)

```bash
# 1. Install the package
npm install @getverdict/mock-bridge --save-dev

# 2. Start the mock (just provide your app URL)
npx @getverdict/mock-bridge http://localhost:3000
```

**就这样!** 您的应用软件现在运行在模拟的商店管理器上 http://localhost:3080

## QQ 快速启动指南

### 第1步: 启动 Moc 服务器

#### 备选案文A: " 一次性启动 " (建议)

```bash
# Simplest - just provide your app URL
npx @getverdict/mock-bridge http://localhost:3000

# Auto-detects client ID from SHOPIFY_API_KEY environment variable
# Auto-detects common app paths and configurations
```

#### 选项B:配置文件

```bash
# Generate a config file
npx @getverdict/mock-bridge init

# Edit the generated mock.config.js, then run:
npx @getverdict/mock-bridge
```

```bash
# Add to package.json scripts for easy access
{
  "scripts": {
    "dev": "next dev",
    "mock:admin": "mock-bridge http://localhost:3000",
    "dev:mock": "concurrently \"npm run dev\" \"npm run mock:admin\""
  }
}
```

#### 备选C:程序化的API

如果您需要更多的控制, 您仍然可以使用程序 API :

```javascript
// scripts/start-mock-admin.js
const { MockShopifyAdminServer } = require("@verdict/mock-bridge");

async function startMockAdmin() {
  const server = new MockShopifyAdminServer({
    appUrl: "http://localhost:3000",
    clientId: process.env.SHOPIFY_API_KEY,
    clientSecret: "mock-secret-12345",
    port: 3080,
    debug: true,
  });

  await server.start();
  console.log("🎉 Mock Shopify Admin ready at http://localhost:3080");
}

startMockAdmin().catch(console.error);
```

### 第2步:前端整合

启用您的应用程序来检测和使用模拟环境 :

#### 备选案文A:自动检测(建议)

替换您的 App 桥脚本装入 :

```html
<!-- Before: Direct CDN loading -->
<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>

<!-- After: Smart loading with mock support -->
<script>
  // Check if we're in a mock environment
  const urlParams = new URLSearchParams(window.location.search);
  const isEmbedded = urlParams.get("embedded") === "1";
  const host = urlParams.get("host");

  let isMockEnvironment = false;

  // Detect mock environment from URL parameters
  if (isEmbedded && host) {
    try {
      const decodedHost = atob(host);
      if (
        decodedHost.includes("localhost") ||
        decodedHost.includes("mock") ||
        window.location.hostname === "localhost"
      ) {
        isMockEnvironment = true;
      }
    } catch (e) {
      // Ignore decode errors
    }
  }

  // Load appropriate App Bridge
  if (isMockEnvironment) {
    console.log("Loading Mock App Bridge");
    const script = document.createElement("script");
    script.src = "http://localhost:3080/app-bridge.js";
    script.onerror = () => {
      // Fallback to real CDN if mock fails
      const fallback = document.createElement("script");
      fallback.src = "https://cdn.shopify.com/shopifycloud/app-bridge.js";
      document.head.appendChild(fallback);
    };
    document.head.appendChild(script);
  } else {
    console.log("Loading Real Shopify App Bridge");
    const script = document.createElement("script");
    script.src = "https://cdn.shopify.com/shopifycloud/app-bridge.js";
    document.head.appendChild(script);
  }
</script>
```

#### 选项 B: 软件包工具( TypeScript)

```typescript
// app.tsx or _app.tsx
import { setupAppBridge } from "@getverdict/mock-bridge/client";

useEffect(() => {
  setupAppBridge({
    debug: true,
    onMockDetected: (mockServerUrl) => {
      console.log("Mock environment detected:", mockServerUrl);
    },
    onShopifyDetected: () => {
      console.log("Real Shopify environment detected");
    },
  })
    .then(() => {
      console.log("App Bridge loaded successfully");
    })
    .catch(console.error);
}, []);
```

### 第3步:后端集成

将您的后端支持模拟会话符号和真实的会话符号一起制作 :

#### 快速集成(取代现有的 JWT 验证)

```typescript
// Before: Only real Shopify tokens
import { verifyShopifyJWT } from "./your-auth";

export async function authenticate(token: string) {
  const authData = await verifyShopifyJWT(token);
  // ... rest of auth logic
}
```

```typescript
// After: Support both real and mock tokens
import {
  validateSessionToken,
  createMockUser,
} from "@getverdict/mock-bridge/auth";

export async function authenticate(token: string) {
  const authData = await validateSessionToken(token, {
    shopifySecret: process.env.SHOPIFY_API_PRIVATE_KEY!,
  });

  if (!authData) {
    throw new Error("Invalid token");
  }

  // Get shop from your database (same for both mock and real)
  const shop = await getShopByName(authData.shopName);
  if (!shop) {
    throw new Error("Shop not found");
  }

  if (authData.isMock) {
    // Mock environment - skip Shopify API calls
    return {
      shop,
      currentUser: createMockUser({
        shopName: authData.shopName,
        permissions: shop.settings?.defaultStaffPermissions,
      }),
      isMock: true,
    };
  } else {
    // Real environment - proceed with normal Shopify flow
    const currentUser = await exchangeTokenForUser(token, shop);
    return {
      shop,
      currentUser,
      isMock: false,
    };
  }
}
```

#### 具体框架实例

**Next.js API 路由:**

```typescript
// pages/api/products.ts
import { validateSessionToken } from "@getverdict/mock-bridge/auth";

export default async function handler(req, res) {
  const token = req.headers.authorization?.replace("Bearer ", "");

  const authData = await validateSessionToken(token, {
    shopifySecret: process.env.SHOPIFY_API_PRIVATE_KEY!,
  });

  if (!authData) {
    return res.status(401).json({ error: "Unauthorized" });
  }

  if (authData.isMock) {
    // Return mock data for testing
    return res.json({
      products: [
        { id: "1", title: "Mock Product 1", price: "19.99" },
        { id: "2", title: "Mock Product 2", price: "29.99" },
      ],
    });
  } else {
    // Fetch real products from Shopify
    const products = await fetchShopifyProducts(authData.shopName);
    return res.json({ products });
  }
}
```

**Express.js Midddleware: (英语)**

```typescript
import {
  validateSessionToken,
  createMockUser,
} from "@getverdict/mock-bridge/auth";

function createAuthMiddleware() {
  return async (req, res, next) => {
    const token = req.headers.authorization?.replace("Bearer ", "");

    const authData = await validateSessionToken(token, {
      shopifySecret: process.env.SHOPIFY_API_PRIVATE_KEY!,
    });

    if (!authData) {
      return res.status(401).json({ error: "Unauthorized" });
    }

    const shop = await getShopByName(authData.shopName);
    req.shop = shop;
    req.isMockAuth = authData.isMock;

    if (authData.isMock) {
      req.currentUser = createMockUser({ shopName: authData.shopName });
    } else {
      req.currentUser = await exchangeTokenForUser(token, shop);
    }

    next();
  };
}

app.use("/api/*", createAuthMiddleware());
```

### 第4步:数据库设置

确保您的模拟商店在数据库中存在 :

```typescript
// Add this to your database seed or setup script
async function setupMockShop() {
  const mockShop = {
    name: "test-shop.myshopify.com",
    displayName: "Mock Test Shop",
    accessToken: "mock-access-token",
    active: true,
    settings: {
      defaultStaffPermissions: [
        "read_products",
        "write_products",
        "read_orders",
        "write_orders",
      ],
    },
  };

  await createOrUpdateShop(mockShop);
  console.log("Mock shop created for testing");
}

// Run during development setup
if (process.env.NODE_ENV === "development") {
  setupMockShop();
}
```

### 第5步:开始发展

```bash
# Option 1: CLI command (simplest)
npx @getverdict/mock-bridge http://localhost:3000

# Option 2: Package.json scripts
npm run dev:mock

# Option 3: Separate terminals
npm run dev                    # Terminal 1: Your app
npm run mock:admin            # Terminal 2: Mock admin
```

**然后导航到:**

-   **你的应用**: http://localhost:3:00
-   **雾化商店管理员**: http://localhost:3080 (英语)
-   **您的应用程序嵌入了模拟管理员**: http://localhost:3080 (自动嵌入您的应用) 互联网档案馆的存檔,存档日期2013-10-21

## CLI 参考

### 快速命令

```bash
# Basic usage with auto-detection
npx @getverdict/mock-bridge http://localhost:3000

# If installed locally, you can use the shorter command:
# npm install @getverdict/mock-bridge --save-dev
# npx mock-bridge http://localhost:3000

# Full configuration
npx @getverdict/mock-bridge http://localhost:3000/shopify \
  --client-id your-client-id \
  --port 3080 \
  --debug

# Using config file
npx @getverdict/mock-bridge init           # Create config file
npx @getverdict/mock-bridge                # Use config file

# Help and version
npx @getverdict/mock-bridge --help
npx @getverdict/mock-bridge --version
```

### CLI 选项

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `[app-url]` | 您的应用程序的 URL( 位置参数) | 从软件包自动发现的。 json |
| `--client-id` | 购买应用程序客户端ID | `$SHOPIFY_API_KEY` |
| `--client-secret` | 模拟客户秘密 | `"mock-secret-12345"` |
| `--shop` | 雾店域名 | `"test-shop.myshopify.com"` |
| `--port` | 移动管理员端口 | `3080` |
| `--config` | 配置文件路径 | `"mock.config.js"` |
| `--debug` | 启用调试日志 | `false` |

### 环境变量

CLI 自动读取这些环境变量:

```bash
SHOPIFY_API_KEY=your-client-id      # Used for --client-id
NODE_ENV=development                # Enables mock token support
```

### 配置文件

生成配置文件 `npx @getverdict/mock-bridge init`数字 :

```javascript
// mock.config.js
module.exports = {
  appUrl: "http://localhost:3000/shopify", // Include path in URL
  clientId: process.env.SHOPIFY_API_KEY,
  clientSecret: "mock-secret-12345",
  port: 3080,
  shop: "test-shop.myshopify.com",
  debug: true,
  scopes: ["read_products", "write_products", "read_orders", "write_orders"],
};
```

## \* 如何运作

### 结构概览

```
┌─────────────────────────────────────┐
│   Mock Shopify Admin (Port 3080)   │
│  ┌─────────────────────────────┐   │
│  │     Shopify Admin UI         │   │
│  │     (Navigation, etc.)       │   │
│  └─────────────────────────────┘   │
│  ┌─────────────────────────────┐   │
│  │   Your App (iframe)          │   │  ← Embedded like real Shopify
│  │   - Mock App Bridge loaded   │   │
│  │   - Gets mock session tokens │   │
│  │   - Makes API calls to your  │   │
│  │     backend                  │   │
│  └─────────────────────────────┘   │
└─────────────────────────────────────┘
         ↕ PostMessage API
┌─────────────────────────────────────┐
│    Your Backend                     │
│    - Validates mock tokens          │  ← Same backend, enhanced auth
│    - Skips Shopify API calls        │
│    - Uses real database             │
│    - Returns mock/real data         │
└─────────────────────────────────────┘
```

### 模拟对真实流

**雾环境(试验):**

1.  Mock 管理员在 Iframe 为您的应用程序服务
2.  Moc App Bridge 提供会话符号
3.  您的前端让 API 呼叫您的后端
4.  后端检测模拟符并跳过 Shopify APIs
5.  直接返回模拟数据或使用数据库

**实际环境(生产):**

1.  Real Shopify 管理员在 Iframe 为您的应用程序服务
2.  Real App 桥提供了会话符号
3.  您的前端让 API 呼叫您的后端
4.  后端检测真实的令牌并呼叫 Shopify API
5.  从 Shostify 返回真实数据

## QQ 配置选项

### 模拟服务器配置

```typescript
const server = new MockShopifyAdminServer({
  // Required
  appUrl: "http://localhost:3000/shopify", // Your app's URL (with path)
  clientId: "your-shopify-client-id", // Your Shopify app's client ID
  clientSecret: "mock-secret-12345", // Mock secret (dev only)

  // Optional
  port: 3080, // Mock admin port
  shop: "test-shop.myshopify.com", // Mock shop domain
  apiVersion: "2024-01", // Shopify API version
  scopes: [
    // Your app's scopes
    "read_products",
    "write_products",
    "read_orders",
    "write_orders",
  ],
  debug: true, // Enable debug logging

  // Admin API handling (see below)
  adminApi: "mock",
});
```

### 管理 API 配置

怎样控制 `fetch('/admin/api/...')` 处理请求:

```javascript
// mock.config.js

// Option 1: Mock data (default) - returns fake data, works offline
module.exports = {
  adminApi: "mock",
};

// Option 2: Proxy through your app - for real data via your backend
module.exports = {
  adminApi: {
    proxy: "http://localhost:3000/api/shopify-proxy",
  },
};

// Option 3: Direct to Shopify - requires access token from installed shop
module.exports = {
  adminApi: {
    accessToken: process.env.SHOPIFY_ACCESS_TOKEN,
  },
};
```

**何时使用每个模式 :**

| 模式 | 使用大小写 |
| --- | --- |
| `'mock'` | 离线测试,CI/CD,不需要购买证书 |
| `{ proxy: '...' }` | 通过您的应用程序后端代理进行真实的数据测试 |
| `{ accessToken: '...' }` | 直接商店化API访问(需要安装商店) |

**代理端点示例** (如果使用代理模式):

```typescript
// pages/api/shopify-proxy.ts (Next.js example)
export default async function handler(req, res) {
  const { url, method, body } = req.body;
  const shop = await getShopFromSession(req);

  const response = await fetch(`https://${shop.domain}${url}`, {
    method,
    headers: {
      "X-Shopify-Access-Token": shop.accessToken,
      "Content-Type": "application/json",
    },
    body: body ? JSON.stringify(body) : undefined,
  });

  res.json(await response.json());
}
```

### 认证选项

```typescript
const authData = await validateSessionToken(token, {
  shopifySecret: process.env.SHOPIFY_API_PRIVATE_KEY!, // Required
  mockSecret: "custom-mock-secret", // Optional
  developmentOnly: true, // Only try mock in dev
});
```

### 模拟用户选项

```typescript
const mockUser = createMockUser({
  shopName: "test-shop.myshopify.com",
  userId: "123456789", // Custom user ID
  email: "test@shop.com", // Custom email
  firstName: "Test", // Custom first name
  lastName: "User", // Custom last name
  permissions: ["read_products"], // Custom permissions
  additionalProps: {
    // Any additional props
    posBillingTermsAcceptedAt: new Date(),
    customField: "value",
  },
});
```

## 使用自动化工具进行测试

### 剧作家示例

```typescript
// playwright.config.ts
import { defineConfig } from "@playwright/test";
import { MockShopifyAdminServer } from "@getverdict/mock-bridge";

let mockServer: MockShopifyAdminServer;

export default defineConfig({
  globalSetup: async () => {
    mockServer = new MockShopifyAdminServer({
      appUrl: "http://localhost:3000",
      clientId: "test-client-id",
      clientSecret: "mock-secret-12345",
      port: 3080,
    });
    await mockServer.start();
  },

  globalTeardown: async () => {
    await mockServer?.stop();
  },

  use: {
    baseURL: "http://localhost:3080",
  },
});
```

```typescript
// tests/app.spec.ts
import { test, expect } from "@playwright/test";

test("should load app in mock Shopify admin", async ({ page }) => {
  await page.goto("/");

  // Wait for app to load in iframe
  const appFrame = page.frameLocator("#app-iframe");

  // Test your app functionality
  await expect(appFrame.locator("h1")).toContainText("Your App Title");

  // Test App Bridge actions
  await appFrame.locator('button:has-text("Show Toast")').click();
  await expect(page.locator(".toast")).toContainText("Success!");

  // Test API calls
  await appFrame.locator('button:has-text("Load Products")').click();
  await expect(appFrame.locator(".product-list")).toBeVisible();
});

test("should handle authentication", async ({ page }) => {
  await page.goto("/");

  const appFrame = page.frameLocator("#app-iframe");

  // Your app should be authenticated automatically
  await expect(appFrame.locator(".user-info")).toContainText("Mock User");
  await expect(appFrame.locator(".shop-info")).toContainText(
    "test-shop.myshopify.com"
  );
});
```

### Jest 集成测试

```typescript
// tests/api.test.ts
import { MockShopifyAdminServer } from "@getverdict/mock-bridge";
import {
  createMockUser,
  validateSessionToken,
} from "@verdict/shopify-app-bridge-mock/auth";

describe("API with Mock Tokens", () => {
  let mockServer: MockShopifyAdminServer;

  beforeAll(async () => {
    mockServer = new MockShopifyAdminServer({
      appUrl: "http://localhost:3000",
      clientId: "test-client",
      clientSecret: "mock-secret-12345",
    });
    await mockServer.start();
  });

  afterAll(async () => {
    await mockServer.stop();
  });

  it("should authenticate with mock token", async () => {
    // Generate mock token
    const token = mockServer.tokenGenerator.generateSessionToken({
      shop: "test-shop.myshopify.com",
      clientId: "test-client",
      clientSecret: "mock-secret-12345",
    });

    // Test authentication
    const authData = await validateSessionToken(token, {
      shopifySecret: "real-secret",
      mockSecret: "mock-secret-12345",
    });

    expect(authData?.isMock).toBe(true);
    expect(authData?.shopName).toBe("test-shop.myshopify.com");
  });

  it("should create mock users", async () => {
    const mockUser = createMockUser({
      shopName: "test-shop.myshopify.com",
      permissions: ["read_products"],
    });

    expect(mockUser.email).toBe("mock@test-shop.com");
    expect(mockUser.permissions).toContain("read_products");
  });
});
```

## 安全考虑

### 仅限开发

模拟符号只用于开发和测试:

```typescript
// ✅ Good: Mock tokens only in development
const authData = await validateSessionToken(token, {
  shopifySecret: process.env.SHOPIFY_API_PRIVATE_KEY!,
  developmentOnly: true, // Default: true
});

// ❌ Bad: Never allow mock tokens in production
const authData = await validateSessionToken(token, {
  shopifySecret: process.env.SHOPIFY_API_PRIVATE_KEY!,
  developmentOnly: false, // Don't do this!
});
```

### 环境变量

在制作时不要有嘲弄性的秘密:

```bash
# .env.local (development only)
SHOPIFY_API_PRIVATE_KEY=your-real-shopify-secret
MOCK_SECRET=mock-secret-12345

# .env.production (no mock secrets)
SHOPIFY_API_PRIVATE_KEY=your-real-shopify-secret
# No MOCK_SECRET in production!
```

### 数据库要求

模拟符号仍然需要您数据库中的有效商店 :

```typescript
// Always verify shop exists, even for mock tokens
const authData = await validateSessionToken(token, options);
if (authData) {
  const shop = await getShopByName(authData.shopName);
  if (!shop) {
    // Reject both mock and real tokens if shop doesn't exist
    throw new Error("Shop not found");
  }
}
```

## \* 解决问题

### 共同问题

**不装入模拟管理员 :**

-   检查 CSP 头部允许 iframe 嵌入
-   校验您的应用程序 URL 在模拟配置中正确
-   确保您的应用程序接受 `embedded=1` 参数

**模拟符号不起作用 :**

-   校验 `NODE_ENV=development`
-   检查前端和后端之间的模拟秘密匹配
-   确保数据库中存在商店

**真正的令牌已损坏 :**

-   校验 `SHOPIFY_API_PRIVATE_KEY` 设置正确
-   请检查date=中的日期值 (帮助) `validateSessionToken`
-   确保保存您现有的 Shopify 认证流

### 调试模式

启用调试日志以排除出错 :

```typescript
// Mock server with debug
const server = new MockShopifyAdminServer({
  // ... config
  debug: true,
});

// Frontend with debug
setupAppBridge({
  debug: true,
  onMockDetected: (url) => console.log("Mock detected:", url),
  onShopifyDetected: () => console.log("Real Shopify detected"),
});
```

### 环境检查

校验您的环境设置 :

```typescript
// Add to your app startup
console.log("Environment:", process.env.NODE_ENV);
console.log("Has Shopify Secret:", !!process.env.SHOPIFY_API_PRIVATE_KEY);
console.log("Mock tokens enabled:", process.env.NODE_ENV === "development");
```

## API 参考

### 认证函数

#### `validateSessionToken(token, options)`

真实和模拟符号的通用验证器.

**参数:**

-   `token: string` - JWT会话符号
-   `options.shopifySecret: string` - 真正的商店客户秘密
-   `options.mockSecret?: string` - 雾密(默认:"雾密-12345")
-   `options.developmentOnly?: boolean` - 只尝试开发中的模拟符号( 默认: 真实)

**回返情况:** `AuthResult | false`

#### `isMockToken(token, mockSecret?)`

快速检查是否是模拟符号 .

**回返情况:** `boolean`

#### `createMockUser(options?)`

生成模拟用户对象进行测试.

**回返情况:** `MockCurrentUser`

#### `withMockTokenSupport(authFunction, shopifySecret, options?)`

将模拟支持添加到现有认证函数中 .

### 服务器类

#### `MockShopifyAdminServer`

主模拟服务器类.

**方法:**

-   `start()` - 启动模拟服务器
-   `stop()` - 停止模拟服务器
-   `getConfig()` - 获得服务器配置

### 客户公用事业

#### `setupAppBridge(options?)`

自动检测模拟环境并装入适当的App Bridge.

**回返情况:** `Promise<void>`

关于完整的API文档,参见: [后端整合指南](https://npmcn.com/package/%40getverdict/mock-bridge/docs/BACKEND_INTEGRATION.md)。 。 。 .

## 捐款

欢迎捐款! 请随意提交问题、特征请求或拉动请求.

### 开发设置

```bash
git clone <repository>
cd packages/shopify-app-bridge-mock
pnpm install
pnpm build
pnpm test
```

## 许可证

麻省理工学院许可证 - 详情见LICENSE文件.

## 承认

-   为 Shopify 开发者社区所建
-   受到需要更好的测试工具的启发
-   感谢所有捐助者和用户

* * *

**与 QQ 一起制作, 供希望测试无痛的 Shopify 开发者使用**

## 常见问题

### @getverdict/mock-bridge 是什么？

用于测试和开发的Mock Shopify App桥

### 如何安装 @getverdict/mock-bridge？

在项目目录运行 npm install @getverdict/mock-bridge，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mock-bridge，可以用 npx mock-bridge 直接运行。

### @getverdict/mock-bridge 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @getverdict/mock-bridge 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @getverdict/mock-bridge 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @getverdict/mock-bridge 可以商用吗？

@getverdict/mock-bridge 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @getverdict/mock-bridge 的下载量有多少？

根据 npm 官方下载统计，@getverdict/mock-bridge 在 2026/10/17 – 2026/11/15 这 30 天内被下载 15,364 次，日均约 512 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @getverdict/mock-bridge 还在维护吗？

最新版本 1\.3\.0 发布于 2026/03/03（8 个月前）；至今共发布 7 个版本，其中过去 12 个月发布了 3 个；首次发布于 2025/10/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

