# @dimension-studios/shop-browser 中文文档

规范地址：https://npmcn.com/package/%40dimension-studios/shop-browser/

版本：1\.223\.0
npm 元数据更新时间：2026-11-10T17:22:44.542Z
中文译文更新时间：2026-11-12T09:55:22.667Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40dimension-studios/shop-browser
原文对照：https://npmcn.com/package/%40dimension-studios/shop-browser/?lang=original
项目主页：https://github.com/dimension-studios-inc/dimension#readme
源码仓库：https://github.com/dimension-studios-inc/dimension

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

- 包体积（解压后）：23.1 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2026-04-29T10:54:41.862Z
- 最新版本发布：2026-11-10T17:22:44.184Z
- 近 30 天下载量：5451（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：341（近 12 个月 341 个）

## 中文简介

使用 TTK 代理 cookie 打开 Chromium 中的 TikTok 商店页面

## 安装

```sh
npm install @dimension-studios/shop-browser
```

也可以使用：`pnpm add @dimension-studios/shop-browser`、`yarn add @dimension-studios/shop-browser`、`bun add @dimension-studios/shop-browser`

## README

# @dimension-studios/shop-浏览器

交互式 CLI 和浏览器扩展来选择 TikTok 商店( 授权用于您的 API 令牌), 从维度加载 cookie **TTK 获取** API,并打开 TikTok Seller / 附属会话 .

使用与 **`@dimension-studios/ttk-proxy`**。可公布的柏油球只包括编译 `dist/` 财务报告和审定财务报表 `bin/` ——没有数据库或内部单列密码.

## 所需资源

-   节点.js ~ 24(匹配单发;见重发) `engines`) (中文(简体) ).
-   全权证书 `/ttk-proxy/*` 端点(API URL + key + secret).
-   后端支持为 **`GET /ttk-proxy/shops/search?q=`** (与曝光TTK代理的节点API一起安装).

## 安装(CLI用户)

```bash
npm install -g @dimension-studios/shop-browser
```

用套件捆绑的 Playwright 版本安装 Chromium( 赤色) `bunx playwright` 拖出最新的 Playwright, 下载不同的 Chromium 构建 :

```bash
# npm global install
node "$(npm root -g)/@dimension-studios/shop-browser/node_modules/playwright-core/cli.js" install chromium
# bun global install (bun add -g)
bun ~/.bun/install/global/node_modules/playwright-core/cli.js install chromium
```

更新后再次运行 `shop-browser` 当它失败时 `Executable doesn't exist at …/ms-playwright/chromium-<build>/…`:新版可以撞倒Playwright并期望一个更新的建筑.

如果铬不能发射,则设定 `EXECUTABLE_PATH` 到您的 Chrome/ Chromium 可执行文件(以下记录) .

## 第一次设置

或设置环境变量(例如您在 shell profile 中),或通过捆绑的配置来坚持这些变量(与 UX 相同) `@dimension-studios/ttk-proxy`:

### 环境变量(建议)

```bash
export TTK_FETCH_API_URL="https://your-node-api.example.com"
export TTK_FETCH_API_KEY="your-api-key"
export TTK_FETCH_API_SECRET="your-api-secret"
```

然后验证:

```bash
shop-browser config
```

### 以配置 : set 保存证书

```bash
shop-browser config:set apiUrl "https://your-node-api.example.com"
shop-browser config:set apiKey "your-api-key"
shop-browser config:set apiSecret "your-api-secret"

shop-browser config --show
```

## CLI 使用情况

运行 **无参数** 启动流量 :

```bash
shop-browser
```

1.  搜索商店的名称或弹片( 至少) **2个字符**) (中文(简体) ). 调查结果只来自您授权的商店.
2.  选择一个目标页面(Seller Center,附属中心,支持消息).
3.  完成时关闭浏览器窗口;进程退出.

添加 `-i` 编号 : `--allow-invalid` 打开一个其储存的饼干不再被标记为有效的商店(失效的商店,过期的登录):

```bash
shop-browser --allow-invalid
```

### 可选环境

| 变量 | 目的 |
| --- | --- |
| `HEADLESS` | 若为 `true` 或者说 `1`,运行 Playwright 无头(默认:可见窗口). |
| `EXECUTABLE_PATH` | 如果不使用被捆绑的 Playwright 浏览器, 通往 Chrome/ Chromium 的路径 . |
| `REMOTE_DEBUGGING_PORT` | 显示本地 Chrome DevTools 端点 `127.0.0.1:<port>` 用于Chrome DevTools MCP等工具. |

复制 `.env.example` 改为 `.env` 仅供地方发展之用;不犯真正的秘密.

要将 Chrome DevTools MCP 附加到打开的浏览器中, 使用调试端口启动 :

```bash
REMOTE_DEBUGGING_PORT=9222 shop-browser
```

然后将 Chrome DevTools MCP 配置为:

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"]
    }
  }
}
```

完成后关闭浏览器, 因此调试端口不再被曝光 .

### 帮助和版本

```bash
shop-browser --help
shop-browser --version
shop-browser config --help
```

## 浏览器扩展

该扩展会在 TikTok 域上向您现有的 Chrome 或 Firefox 浏览器注入商店 cookie(`*.tiktok.com`, (中文(简体) ), `*.tiktokshop.com`, (中文(简体) ), `*.tiktokglobalshop.com`) (中文(简体) ).

### 构建扩展 (Monorepo)

```bash
bun install
bun run --cwd tools/shop-browser build:extension
```

这产生了:

-   `tools/shop-browser/dist/extension/chrome` - 已拆开的Chrome扩展
-   `tools/shop-browser/dist/extension/firefox` —已解开的Firefox扩展名(用于调试)
-   `tools/shop-browser/dist/extension/dimension-shop-browser.xpi` — Firefox 添加文件
-   `tools/shop-browser/dist/extension/dimension-shop-browser-chrome.zip` —已拉链的Chrome扩展

扩展图标从 `extension/icons/` (从 `apps/app/public/icons/icon.svg`) (中文(简体) ).

### 在 Chrome 安装

1.  打开 `chrome://extensions`
2.  启用 **开发者模式**
3.  点击 **装入已卸出**
4.  选择 `tools/shop-browser/dist/extension/chrome`

### 在 Firefox 中安装

要求数 **消防狐127** 或后会.

**标准Firefox发布 :** 正常放行时未署名的Mozilla区块会建起. 使用下面的临时安装流程进行本地开发,或者安装一个通过AMO或您的组织分发的签名的XPI. Firefox 清单宣布需要数据收集权限(`authenticationInfo`, (中文(简体) ), `searchTerms`),所以加成可以通过AMO验证,用于该已签名的分发路径.

**永久安装( 未签名, 专用 Firefox 建筑):**

仅在 Firefox 上使用 **爱沙尼亚**, (中文(简体) ), **开发者版**, (中文(简体) ), **夜来**,或者其他 **无品牌** 在允许未署名加注的地方建造。 在标准发布 Firefox, 设置 `xpinstall.signatures.required` 改为 `false` 已经 **没有** 允许永久未签名的安装.

1.  打开 `about:config` 设置 `xpinstall.signatures.required` 改为 `false`。 。 。 .
2.  打开 `about:addons`
3.  点击齿轮图标 {} **从文件安装添加..**
4.  选择 `tools/shop-browser/dist/extension/dimension-shop-browser.xpi`

**临时安装( 建议用于标准 Firefox; 重新启动时删除) :**

1.  打开 `about:debugging#/runtime/this-firefox`
2.  点击 **装入临时加载**
3.  选择 `tools/shop-browser/dist/extension/firefox/manifest.json`

### 扩展使用

1.  用应用程序来源构建扩展名 `tools/shop-browser/.env` (单位:千美元)`NEXT_PUBLIC_APP_URL`,或 `TTK_FETCH_API_URL` 犹如退后.
2.  打开扩展名并单击 **签名到尺寸** 如果您尚未签名 `app.dimensionstudios.co`。 。 。 .
3.  搜索商店( 最少 **2个字符**)并选择. 结果仅限于您可以进入当前组织的商店.
4.  转弯 **自动注入** 当打开 TikTok 域时, 或使用时, 将插入 cookie **现在注射** 手动.
5.  转动自动注射 **关** 停止未来的注入, 并让已有的浏览器 cookie 不受影响 .

### IAM 许可

用户需要 **使用商店浏览器扩展** 权限( e)`SHOP_BROWSER_EXTENSION_ACCESS`),用于他们所注入的每一家商店. 组织管理人员可以从全组织或商店范围的IAM团体获得。 这个权限暴露出原始的TikTok shop会话 cookie,并有效地让用户在他们的浏览器中充当该商店的管理员——只给予信任的用户.

CLI 继续使用 API URL + key + secret(`TTK_FETCH_API_*`;只有浏览器扩展使用SaaS会话 cookie.

### CI/CD发布

当 `@dimension-studios/shop-browser` 是通过 [语义释放](https://github.com/semantic-release/semantic-release) 打开 `main-release`。 。 。 .

**线人做什么**

1.  弹出 npm 软件包版本(与 CLI 相同的发布).
2.  以 `NEXT_PUBLIC_APP_URL` 从 GitHub 动作 vars (有线于 `.github/workflows/release.yml`) (中文(简体) ). 扩展列表版本来自 `@dimension-studios/shop-browser` `package.json` (与CI上的语义-放出版本相配合).
3.  附加释放文物到 GitHub 释放 :
    -   `dimension-shop-browser.xpi` — Firefox 添加内容
    -   `dimension-shop-browser-chrome.zip` - Chrome可拆卸扩展(上载至Chrome Web Store或已拆卸)

**所需的 GitHub 配置**

-   仓库变量 : `NEXT_PUBLIC_APP_URL` (例如:. `https://app.dimensionstudios.co` 用于生产释放物.

**从释放安装**

1.  打开 [GitHub 发布](https://github.com/dimension-studios-inc/dimension/releases) 此重播页面.
2.  从最近下载 XPI 或 Chrome ZIP `@dimension-studios/shop-browser` 释放.
3.  **Firefox: (英语)** 安装 XPI(签名的 AMO 分布仍需要单独的 Mozilla 提交) .
4.  **颜色 :** 上传 ZIP 到 [Chrome Web Store 开发者仪表板](https://chrome.google.com/webstore/devconsole),或卸下并装入行李进行内部测试.

CI 还运行 `bun run --cwd tools/shop-browser build:extension` 每一次拉动请求`.github/workflows/check.yml`) 早期捕捉到建立回归.

### 自动存储列表( Chrome + Firefox)

打开 **`main-release`** 只有在语义释放成功之后,CI才会将已建扩展提交:

-   **Chrome 网页存储器** ——通过上传+发布 `chrome-webstore-upload-cli`
-   **Firefox 添加子 (AMO) (英语)** ——通过 `web-ext sign` (提交 API 在 Web-ext 8+ 中默认)

#### 一次性开发者设置

**Chrome 网页存储器**

1.  在 [Chrome Web Store 开发者仪表板](https://chrome.google.com/webstore/devconsole) (第一次上传可以是手动的).
2.  启用 [Chrome 网络存储 API](https://developer.chrome.com/docs/webstore/using-api) 谷歌云计划.
3.  创建 OAuth 证书并生成刷新符号 - [铬-网球-上载键](https://github.com/fregante/chrome-webstore-upload-keys) 穿过这个.
4.  请注意你 **发布者 ID** (开发仪表板)和 **扩展代号** (从列表 URL 或 `chrome://extensions` 当装入行李时.

**Firefox 添加点数**

1.  创建附加于 [(原始内容存档于2018-10-21). addons.mozila.org](https://addons.mozilla.org/developers/) (名单).
2.  生成 **JWT API证书** (发卡人+秘密)来自开发商枢纽.
3.  扩展名ID已经设置在 `extension/manifest.firefox.json`数字 : `dimension-shop-browser@dimensionstudios.co`。 。 。 .

#### GitHub 秘密( 存储)

| 秘诀 | 说明 |
| --- | --- |
| `SHOP_BROWSER_CHROME_EXTENSION_ID` | Chrome 扩展 ID (32- Char字符串) |
| `SHOP_BROWSER_CHROME_PUBLISHER_ID` | Chrome Web Store 发布器 ID |
| `SHOP_BROWSER_CHROME_CLIENT_ID` | 谷歌 OAuth 客户端ID |
| `SHOP_BROWSER_CHROME_CLIENT_SECRET` | Google OAuth 客户端秘密( 平面) `GOCSPX-…` 来自 Google Cloud 的值) |
| `SHOP_BROWSER_CHROME_REFRESH_TOKEN` | 谷歌 OAuth 刷新令牌 |
| `SHOP_BROWSER_AMO_JWT_ISSUER` | AMO JWT发行商(`user:…`(中文(简体) ) |
| `SHOP_BROWSER_AMO_JWT_SECRET` | AMO JWT秘密组织 |

如果缺少任何商店的秘密,该商店会被跳出(释放仍然成功). 两家店都要求各自保密.

#### 手工商店出版(当地)

生产之后 `NEXT_PUBLIC_APP_URL`数字 :

```bash
export NEXT_PUBLIC_APP_URL=https://app.dimensionstudios.co
bun run --cwd tools/shop-browser build:extension

# Set the same SHOP_BROWSER_* secrets as in GitHub, then:
bun run --cwd tools/shop-browser publish:stores
```

新版本在提交后输入每个商店的审查队列;批准由Google/Mozilla处理.

## 发展(在这个单列中)

```bash
bun install
bun run --cwd tools/shop-browser build
bun run --cwd tools/shop-browser build:extension
bun run --cwd tools/shop-browser type-check
```

从源代码运行 CLI( expects env 通过 `dotenv` / 链接根 `.env`:

```bash
bun run --cwd tools/shop-browser start
# or from repo root:
bun run tools:isb
```

弹出/ 背景变化后重建扩展名 :

```bash
bun run --cwd tools/shop-browser dev:extension
```

然后在浏览器中重新装入已打开的扩展 .

## 相关软件包

-   **`@dimension-studios/ttk-proxy`** ——从终端调用 TTK 代理 API,包括 `ttk-proxy shops <query>` 用于调试商店搜索.

## 许可证

公务员制度委员会

## 作者

尺寸工作室

## 常见问题

### @dimension-studios/shop-browser 是什么？

使用 TTK 代理 cookie 打开 Chromium 中的 TikTok 商店页面

### 如何安装 @dimension-studios/shop-browser？

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

### @dimension-studios/shop-browser 支持 TypeScript 吗？

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

### @dimension-studios/shop-browser 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dimension-studios/shop-browser 可以商用吗？

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

### @dimension-studios/shop-browser 的下载量有多少？

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

### @dimension-studios/shop-browser 还在维护吗？

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