vtex-io-app-structure

应用架构与清单配置

何时适用此技能

在处理 VTEX IO 应用的基础结构时使用此技能，包括 manifest.json 文件、builder 系统、策略声明、依赖管理、service.json 资源限制，以及应用生命周期（link、publish、deploy）。

• 从头创建 VTEX IO 应用
• 为现有应用添加 builder
• 配置 API 访问策略
• 排查与 manifest 配置错误相关的部署失败

以下情况请勿使用此技能：

• 后端服务实现细节（请改用 vtex-io-service-apps）
• React 组件开发（请改用 vtex-io-react-apps）
• GraphQL 架构和解析器细节（请改用 vtex-io-graphql-api）

决策规则

• 每个 VTEX IO 应用都从 manifest.json 开始——它定义身份（vendor、name、version）、builders、依赖项和策略。
• 使用与目录匹配的 builder：/node 使用 node，/react 使用 react，/graphql 使用 graphql，/admin 使用 admin，/pixel 使用 pixel，/messages 使用 messages，/store 使用 store，/masterdata 使用 masterdata，/styles 使用 styles。
• 为应用调用的每个外部主机以及访问的每项 VTEX Admin 资源声明策略。
• 在 /node 中使用 service.json 配置内存（最多 512MB）、超时、自动扩缩和路由定义。
• 依赖项使用 semver 范围（3.x），而非精确版本。
• 对于必须存在但不应自动安装的应用，请使用 peerDependencies。

Builders 参考：

Builder	目录	用途
node	/node	使用 TypeScript 编写的后端服务（中间件、解析器、事件处理程序）
react	/react	使用 TypeScript/TSX 编写的前端 React 组件
graphql	/graphql	GraphQL 架构定义（.graphql 文件）
admin	/admin	管理面板页面和导航条目
pixel	/pixel	向店面注入脚本的 Pixel/追踪应用
messages	/messages	国际化——每种区域设置对应的本地化字符串文件
store	/store	Store Framework 主题区块、接口和路由
masterdata	/masterdata	Master Data v2 实体架构和触发器
styles	/styles	Store Framework 主题的 CSS/Tachyons 配置

策略类型：

1. 出站访问策略：授予对明确指定 URL（外部 API 或 VTEX 端点）的访问权限。
2. License Manager 策略：使用资源键授予对 VTEX Admin 资源的访问权限。
3. 基于应用角色的策略：授予对其他 IO 应用公开的路由或 GraphQL 查询的访问权限，格式为 {vendor}.{app-name}:{policy-name}。

架构：

manifest.json
├── builders → determines which directories are processed
│   ├── node/ → compiled by node builder → backend service
│   ├── react/ → compiled by react builder → frontend bundles
│   ├── graphql/ → compiled by graphql builder → schema/resolvers
│   ├── store/ → compiled by store builder → theme blocks
│   ├── admin/ → compiled by admin builder → admin pages
│   ├── pixel/ → compiled by pixel builder → tracking scripts
│   └── messages/ → compiled by messages builder → i18n strings
├── policies → runtime permissions for API access
├── dependencies → other VTEX IO apps this app requires
└── peerDependencies → apps required but not auto-installed

硬性约束

约束：声明所有必需的 Builders

应用中每个包含可处理代码的目录都必须在 manifest.json 中声明对应的 builder。如果有 /node 目录，就必须声明 node builder。如果有 /react 目录，就必须声明 react builder。

为何重要

如果未声明 builder，VTEX IO 平台会完全忽略该目录。后端代码不会编译，React 组件不会渲染，GraphQL 架构也不会注册。应用可以成功 link，但功能会悄然缺失。

检测方法

如果你在 /node 目录中看到后端 TypeScript 代码，但 manifest 未在 builders 中声明 "node": "7.x"，请立即停止并添加该 builder。/react 未声明 "react": "3.x"、/graphql 未声明 "graphql": "1.x" 等情况也同样如此。

正确

{
  "name": "my-service-app",
  "vendor": "myvendor",
  "version": "1.0.0",
  "title": "My Service App",
  "description": "A backend service app with GraphQL",
  "builders": {
    "node": "7.x",
    "graphql": "1.x",
    "docs": "0.x"
  },
  "dependencies": {},
  "policies": []
}

错误

{
  "name": "my-service-app",
  "vendor": "myvendor",
  "version": "1.0.0",
  "title": "My Service App",
  "description": "A backend service app with GraphQL",
  "builders": {
    "docs": "0.x"
  },
  "dependencies": {},
  "policies": []
}

缺少 node 和 graphql builders——/node 和 /graphql 目录会被完全忽略。后端代码不会编译，GraphQL 架构也不会注册。应用 link 时不会报错，但任何功能都无法使用。

---

约束：为所有外部访问声明策略

每次外部 API 调用或 VTEX 资源访问都必须在 manifest.json 中有对应的策略。这包括对外部主机的出站 HTTP 调用、VTEX Admin 资源访问，以及对其他应用的 GraphQL API 的调用。

原因

VTEX IO 会对应用进行沙箱隔离以保障安全。没有正确的策略，任何出站 HTTP 请求都会在基础设施层被拦截，并返回 403 Forbidden 错误。这不是代码问题，而是平台级限制。

检测

如果看到代码通过客户端或 HTTP 向某个主机发起 API 调用，请立即停止并确认清单中是否存在针对该主机的 outbound-access 策略。如果看到 licenseManager.canAccessResource(...)，请确认是否存在 License Manager 策略。

正确

{
  "policies": [
    {
      "name": "outbound-access",
      "attrs": {
        "host": "api.vtex.com",
        "path": "/api/*"
      }
    },
    {
      "name": "outbound-access",
      "attrs": {
        "host": "portal.vtexcommercestable.com.br",
        "path": "/api/*"
      }
    },
    {
      "name": "ADMIN_DS"
    },
    {
      "name": "colossus-fire-event"
    },
    {
      "name": "colossus-write-logs"
    }
  ]
}

错误

{
  "policies": []
}

策略数组为空，但应用却调用 api.vtex.com 并使用 Master Data。所有出站请求在运行时都会失败并返回 403 Forbidden 错误，而且很难排查。

---

约束：遵循应用命名规范

应用名称必须采用 kebab-case（由连字符分隔的小写字母）。vendor 必须与 VTEX 账户名称一致。版本必须遵循 Semantic Versioning 2.0.0。

原因

名称无效的应用无法发布到 VTEX App Store。包含特殊字符或大写字母的名称会被 builder-hub 拒绝。Vendor 不匹配会导致账户无法管理该应用。

检测

如果看到应用名称中包含大写字母、下划线、特殊字符，或以数字开头，请立即停止并修正名称。

正确

{
  "name": "order-status-dashboard",
  "vendor": "mycompany",
  "version": "2.1.3"
}

错误

{
  "name": "Order_Status_Dashboard",
  "vendor": "mycompany",
  "version": "2.1"
}

名称中的大写字母和下划线会导致应用被拒绝。版本“2.1”不符合 semver 规范，必须写作“2.1.0”。

推荐模式

使用 VTEX IO CLI 初始化：

vtex init

选择合适的模板：service-example、graphql-example、react-app-template 或 store-theme。

推荐的清单配置：

{
  "name": "product-review-service",
  "vendor": "mycompany",
  "version": "0.1.0",
  "title": "Product Review Service",
  "description": "Backend service for managing product reviews with GraphQL API",
  "builders": {
    "node": "7.x",
    "graphql": "1.x",
    "docs": "0.x"
  },
  "dependencies": {
    "vtex.search-graphql": "0.x"
  },
  "policies": [
    {
      "name": "outbound-access",
      "attrs": {
        "host": "api.vtex.com",
        "path": "/api/*"
      }
    },
    {
      "name": "ADMIN_DS"
    },
    {
      "name": "colossus-fire-event"
    },
    {
      "name": "colossus-write-logs"
    }
  ]
}

后端应用推荐使用的 service.json：

{
  "memory": 256,
  "timeout": 30,
  "minReplicas": 2,
  "maxReplicas": 10,
  "workers": 4,
  "routes": {
    "reviews": {
      "path": "/_v/api/reviews",
      "public": false
    },
    "review-by-id": {
      "path": "/_v/api/reviews/:id",
      "public": false
    }
  }
}

推荐的目录结构：

my-app/
├── manifest.json
├── package.json
├── node/
│   ├── package.json
│   ├── tsconfig.json
│   ├── service.json
│   ├── index.ts          # Service entry point
│   ├── clients/
│   │   └── index.ts      # Client registry
│   ├── middlewares/
│   │   └── validate.ts   # HTTP middleware
│   └── resolvers/
│       └── reviews.ts    # GraphQL resolvers
├── graphql/
│   ├── schema.graphql    # Query/Mutation definitions
│   └── types/
│       └── Review.graphql
├── messages/
│   ├── en.json
│   ├── pt.json
│   └── es.json
└── docs/
    └── README.md

使用多个 builders 的综合应用完整 manifest.json：

{
  "name": "product-review-suite",
  "vendor": "mycompany",
  "version": "1.0.0",
  "title": "Product Review Suite",
  "description": "Complete product review system with backend, frontend, and admin panel",
  "mustUpdateAt": "2026-01-01",
  "builders": {
    "node": "7.x",
    "react": "3.x",
    "graphql": "1.x",
    "admin": "0.x",
    "messages": "1.x",
    "store": "0.x",
    "docs": "0.x"
  },
  "dependencies": {
    "vtex.styleguide": "9.x",
    "vtex.store-components": "3.x",
    "vtex.css-handles": "0.x"
  },
  "peerDependencies": {
    "vtex.store": "2.x"
  },
  "policies": [
    {
      "name": "outbound-access",
      "attrs": {
        "host": "api.vtex.com",
        "path": "/api/*"
      }
    },
    {
      "name": "ADMIN_DS"
    },
    {
      "name": "colossus-fire-event"
    },
    {
      "name": "colossus-write-logs"
    }
  ],
  "settingsSchema": {
    "title": "Product Review Suite Settings",
    "type": "object",
    "properties": {
      "enableModeration": {
        "title": "Enable review moderation",
        "type": "boolean"
      },
      "reviewsPerPage": {
        "title": "Reviews per page",
        "type": "number"
      }
    }
  }
}

常见故障模式

• 声明未使用的 builders：添加“以防万一”的 builders 会增加构建过程的开销。未使用的 builder 目录可能导致构建警告。只声明应用实际使用的 builders。
• 通配符出站策略：使用 "host": "*" 或 "path": "/*" 存在安全风险，会在应用审核时被拒绝，也会增加安全审计难度。为每个外部服务声明具体策略。
• 在依赖项中硬编码版本：固定精确版本，例如 "vtex.store-components": "3.165.0"，会导致无法接收错误修复。请使用带 x 通配符的主版本范围："vtex.store-components": "3.x"。

审核清单

• 每个代码目录（/node、/react、/graphql 等）是否都在 manifest.json 中有对应的 builder？
• 是否已在 policies 中声明所有外部主机和 VTEX 资源？
• 应用名称是否采用 kebab-case、vendor 是否与账户匹配、版本是否符合 semver 规范？
• 使用 node builder 的应用是否包含 service.json？
• 依赖项是否使用主版本范围（3.x），而非精确版本？
• 占位值（vendor、应用名称、policies）是否都已替换为实际值？

参考

• 清单 — 完整介绍所有 manifest.json 字段及其用法
• 构建器 — 可用构建器的完整列表，以及说明和用法示例
• 策略 — 如何声明出站访问、License Manager 和基于角色的策略
• 依赖项 — 管理应用依赖项和对等依赖项
• 访问外部资源 — 用于访问外部 API 的策略类型和模式
• 创建新应用 — 应用初始化分步指南