tapcart-project

Tapcart 项目

针对 Tapcart CLI 项目的全局操作。所有命令均从 Tapcart 项目目录的根目录运行。

除非另有说明，否则你（Agent）直接运行所有命令。

---

首次设置

按顺序完成以下步骤，帮助用户从零开始搭建可正常使用的本地环境。

步骤 1 — 检查 Node.js

node --version

需要 Node 23 或更高版本。如果未安装或版本过旧，请告知用户从 https://nodejs.org 安装（最新的 LTS 版本 ≥ 23）。Node.js 是一次性系统前置条件——等待用户确认安装完成后再继续。

步骤 2 — 全局安装 Tapcart CLI

npm install -g @tapcart/tapcart-cli

验证是否安装成功：

tapcart --version

步骤 3 — 获取 App ID

询问用户的 Tapcart App ID。用户可以在此处找到： https://app.tapcart.com/settings → Tapcart CLI API Key 部分

步骤 4 — 创建项目（如果项目已存在则跳过）

检查当前目录中是否已有 tapcart.config.json。如果有，跳至步骤 5。

如果项目不存在，请创建一个：

npm init @tapcart/tapcart-app@latest -- -a <app-id> -f <folder-name>
cd <folder-name>
npm install

步骤 5 — 身份验证

运行此命令——它会自动打开浏览器窗口，并在用户完成 OAuth 登录前保持阻塞：

tapcart auth login

命令退出后，身份验证即完成。继续下一步。

步骤 6 — 拉取现有区块和组件

tapcart block pull -a
tapcart component pull -a

项目现在已准备就绪。

---

身份验证

# Log in (opens browser automatically, blocks until complete)
tapcart auth login

# Log out
tapcart auth logout

凭据存储在本地，并会在不同会话间保留。

---

依赖项

依赖项是可以在区块中导入的 npm 包。必须在本地添加，并推送到远程应用配置中，才能在控制面板或移动应用中使用。

# Add a dependency
tapcart dependency add lodash 4.17.21

# Remove a dependency
tapcart dependency remove lodash

# List local dependencies
tapcart dependency list

# Pull dependencies from remote app config
tapcart dependency pull

# Push local dependency list to remote app config
tapcart dependency push

添加依赖项后，提醒用户将包名添加到相关区块的 config.json 中的 "dependencies": []，然后运行 tapcart dependency push。

---

代码检查

运行代码检查并向用户展示输出：

# Lint all blocks and components
tapcart lint --all

# Lint specific blocks
tapcart lint -b MyBlock -b AnotherBlock

# Lint specific components
tapcart lint -c ProductCard

# Lint with auto-fix (writes changes to disk)
tapcart lint --all --fix
tapcart lint -b MyBlock --fix

向用户展示代码检查输出，并在使用 --fix 运行前征求确认。

---

日志

tapcart log

---

布局开发服务器

在后台运行布局开发服务器，并告知用户服务器正在运行。持续运行，直到用户要求停止。

# Prompts interactively for layout type if not provided
tapcart layout dev

# Specify layout type
tapcart layout dev -l home

# Specify layout type and a particular layout ID
tapcart layout dev -l home -v <layoutId>

# Override specific blocks with their local version
tapcart layout dev -l home -b MyBlock -b AnotherBlock

# Override all blocks with local versions
tapcart layout dev -l home -a

# Custom port (default is 4995)
tapcart layout dev -l home -p 4995

默认情况下，开发服务器使用控制面板的线上版本渲染区块。使用 -b <BlockFolderName> 改用本地区块，或使用 -a 使用所有本地区块。

用户要求停止开发服务器时，终止该进程。