如何构建并发布 Twenty 应用tarball 部署到服务器或上架 npm 市场【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty一个 Twenty 应用完成本地开发和测试后有两条官方分发路径把 tarball 直接部署到某个 Twenty 服务器内部或私有使用或发布到 npm 上架 Twenty 市场任何 workspace 可发现并安装。两条路径都从同一个构建命令开始。本文按顺序给出两条路径的操作命令、安装验证方式和常见报错适用于已经能通过npx create-twenty-app生成项目并本地跑通的应用。准备条件发布前确认以下条件来自文档 Quick Start 的 Prerequisites 一节Node.js 24.5与Yarn 4通过 Corepack 启用corepack enable已有应用源码且在本地构建/测试通过tarball 路径需要一个可达的目标 Twenty 服务器npm 路径需要一个npm 账号如果本地已有 Twenty 在运行不需要额外装 Docker本地开发服务器可用yarn twenty docker:start管理两条路径的共同第一步构建yarn twenty dev:build该命令编译 TypeScript 源码、转译 logic functions 和 front components把所有产物写入.twenty/output/并生成一份可分发的manifest.json。加上--tarball参数会额外打出一个.tgz包用于手动分发或发布命令。发布前建议先跑一遍与 CI 相同的检查来自 Publishing 教程yarn lint # oxlint yarn typecheck # tsgo yarn test:unit # 单元测试 yarn twenty plan # 预览元数据 diff不实际应用plan只打印会在服务器上产生什么变化、并不应用适合作为发布前的最后一步确认。路径一tarball 部署到服务器适合不希望公开的应用自研工具、企业专属集成、实验性构建。1. 配置指向目标服务器的 remoteremote 保存服务器 URL 和认证凭据存放在本地的~/.twenty/config.json。先添加一个 remote命令中的https://your-twenty-server.com为文档占位地址替换为你的真实服务器 URL--as production指定该 remote 的名称yarn twenty remote:add --url https://your-twenty-server.com --as production在 CI 等无交互环境可加 API key 非交互添加见 CLI 文档yarn twenty remote:add --url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote用yarn twenty remote:list列出已配置的 remote用yarn twenty remote:status检查当前激活 remote 的认证是否仍然有效。2. 部署构建并上传一步完成yarn twenty app:publish --private # 部署到指定 remote # yarn twenty app:publish --private --remote production不带--private的yarn twenty app:publish是发布到 npm--private才是上传 tarball 到服务器的私有注册表。3. 验证与共享在 Twenty UI 的Settings Applications页面可以浏览并安装已部署的应用。tarball 应用不会出现在公开市场同一服务器上的其他 workspace 无法通过浏览发现它。要共享给其他 workspace进入Settings Applications Registrations打开你的应用在Distribution标签点击Copy share link把链接发给其他 workspace 的用户链接直达该应用的安装页share link 使用服务器基础 URL不含 workspace 子域因此对服务器上任意 workspace 都有效。4. 更新版本时的规则更新已部署的 tarball 应用时package.json里的version必须按 semver 排序严格高于当前已部署版本。重复部署同版本或推送更低版本会在 tarball 落盘前被拒绝CLI 报VERSION_ALREADY_EXISTS。发布更新的步骤提升package.json的version例如1.2.3→1.2.4、1.3.0或2.0.0重新执行yarn twenty app:publish --private对已安装该应用且开启了自动升级应用 Settings 标签中的 workspace后台自动升级其余 workspace 会在设置中看到可用升级文档明确了预发布规则1.0.0-rc.1→1.0.0-rc.2是允许的1.0.0会被正确识别为高于1.0.0-rc.5package.json中的 version 本身必须是合法 semver 字符串。5. 声明最低服务器版本可选如果应用用到了某个 Twenty 服务器版本才引入的功能用package.json的engines.twenty声明最低服务器版本该字段同时也是本地yarn twenty docker:start解析镜像版本的依据{ name: twenty-my-app, version: 1.0.0, engines: { node: ^24.5.0, twenty: 2.3.0 } }值是标准 semver 范围2.3.0表示 2.3.0 及以后任意版本^2.3.0等价于2.3.0 3.0.0。行为规则engines.twenty已设置且目标服务器版本不满足范围时部署tarball 上传或安装都会被拒绝报SERVER_VERSION_INCOMPATIBLE错误信息中同时给出要求范围和服务器实际版本未设置engines.twenty时应用在任何服务器版本上都被接受向后兼容服务器未配置APP_VERSION时该检查被跳过。服务器是权威检查方无论是带外部署 tarball 还是从市场安装服务器都会强制校验兼容性。路径二发布到 npm上架 Twenty 市场1. 前置配置一个 npm 账号package.json的keywords数组里加twenty-app—— 这一步需要手动添加create-twenty-app模板默认不包含{ name: twenty-app-postcard-sender, version: 1.0.0, keywords: [twenty-app] }2. 市场元数据可选但影响展示defineApplication()配置中的可选字段控制应用在市场中的展示。logo和galleryImages引用public/目录里的图片export default defineApplication({ universalIdentifier: ..., displayName: My App, description: A great app, logo: public/logo.png, galleryImages: [ public/screenshot-1.png, public/screenshot-2.png, ], });限制与行为市场的galleryImages容器固定为8:5比例例如1600×1000 px。任意比例的图都会完整显示、不会被裁剪但明显偏高或偏窄的图两侧会留空边logo和每个galleryImages文件不得超过10 MB超出的文件在市场重新托管你的发布资产时会被跳过即不会显示未在defineApplication()中定义aboutDescription时市场自动使用 npm 包中的README.md作为 About 页内容想在市场显示不同描述就显式设置aboutDescription。完整字段列表author、category、websiteUrl、termsUrl等见 Application Config 文档 的 Marketplace metadata 一节。3. 发布yarn twenty app:publish # 发布到指定 dist-tag如 beta、next yarn twenty app:publish --tag beta该命令会构建应用并把.twenty/output发布到 npm。4. 触发市场目录同步Twenty 服务器每小时从 npm registry 同步一次市场目录。不想等的话立即触发--remote可指定目标 remoteyarn twenty dev:catalog-sync # yarn twenty dev:catalog-sync --remote production同步完成后市场里显示的元数据即来自你的defineApplication()配置。安装验证两条路径通用应用发布npm或部署tarball后workspace 通过 UI 安装打开 Twenty 的Settings Applications页面市场应用和 tarball 部署的应用都能在此浏览并安装。也可以用命令行yarn twenty app:install服务器在安装时强制 semver 规则与部署规则对应安装与当前已安装相同的版本 → 报APP_ALREADY_INSTALLED安装低于当前已安装版本的版本 → 报CANNOT_DOWNGRADE_APPLICATION要安装更高版本先部署或发布新版本再重新执行yarn twenty app:install排查与限制Registration 归属被拒。发布应用会创建一个 application registration应用在该实例上的身份所有安装它的 workspace 共享。universalIdentifier在整个实例内唯一一个 registration 最多属于一个 workspaceowner。安装和开发是两种不同的权利操作要求安装应用应用已上架市场、被运营者预装、或 registration 属于你的 workspace开发应用yarn twenty dev、apply、planregistration 属于你的 workspace两种情况会导致拒绝identifier 属于另一个 workspace修改应用配置中的universalIdentifier这是 fork 他人应用时的通常做法如需保留原 identifier必须由 owner workspace 把 registration 转移给你。identifier 不属于任何 workspace从市场目录同步导入的应用初始是无主的需要先通过 npm trusted publishing 认领再在其上开发。从私有仓库发布的 provenance 问题。npm 只接受来自公开源码仓库的 provenance。从私有仓库发布时npm 会以E422 ... Unsupported GitHub Actions source repository visibility: private拒绝 OIDC provenance 包。确需从私有仓库发布时在publish.yml发布步骤的env中设置TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: true关闭 provenance。cd.yml 的默认部署地址不可用。模板生成的cd.yml中TWENTY_DEPLOY_URL默认为http://localhost:3000这只是占位值GitHub 托管 runner 无法访问。启用 CD 前必须把它改成你服务器的公网 URL或改用有网络可达性的自托管 runner。可选用模板内置的 CI 自动化create-twenty-app生成的应用在.github/workflows/下自带三个 GitHub Actions 工作流工作流行为需要的配置ci.yml每次 push 到main和每次 PR 跑集成测试启动临时 Twenty 测试实例无 secrets可用TWENTY_VERSIONenv 固定 CI 使用的服务器版本cd.yml每次 push 到main自动执行app:publish --private并安装到目标 workspace给 PR 加deploy标签可触发预览部署env中的TWENTY_DEPLOY_URL Actions Secrets 中具备部署权限的TWENTY_DEPLOY_API_KEYpublish.ymlpush 版本 tag如v1.0.0或在 Actions 页手动触发时发布到 npm带 provenance一次性在 npm 官网该包的 Settings → Trusted Publisher 注册本仓库与publish.yml工作流npm 需 11.5.1publish.yml中无需写 npm 参数CI 里运行yarn twenty app:publish时会自动加上--provenance和--access public。provenance 同时是你在 Twenty 市场中认领应用所有权的方式。其他 CI 系统GitLab CI、CircleCI 等直接yarn install后运行yarn twenty app:publish即可环境能签发 OIDC token 时会输出 provenance否则自动跳过。ci.yml/cd.yml引用的可复用 action 默认指向main需要确定性构建时可把每行uses:改为 commit SHA 或 release tag。相关文档Publishing两条分发路径的完整参考CLIyarn twenty全部命令与 remote 管理Application ConfigdefineApplication()与全部市场元数据字段Quick Start搭建应用与本地开发环境Testing发布前的测试与类型检查【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何构建并发布 Twenty 应用：tarball 部署到服务器或上架 npm 市场？
如何构建并发布 Twenty 应用tarball 部署到服务器或上架 npm 市场【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty一个 Twenty 应用完成本地开发和测试后有两条官方分发路径把 tarball 直接部署到某个 Twenty 服务器内部或私有使用或发布到 npm 上架 Twenty 市场任何 workspace 可发现并安装。两条路径都从同一个构建命令开始。本文按顺序给出两条路径的操作命令、安装验证方式和常见报错适用于已经能通过npx create-twenty-app生成项目并本地跑通的应用。准备条件发布前确认以下条件来自文档 Quick Start 的 Prerequisites 一节Node.js 24.5与Yarn 4通过 Corepack 启用corepack enable已有应用源码且在本地构建/测试通过tarball 路径需要一个可达的目标 Twenty 服务器npm 路径需要一个npm 账号如果本地已有 Twenty 在运行不需要额外装 Docker本地开发服务器可用yarn twenty docker:start管理两条路径的共同第一步构建yarn twenty dev:build该命令编译 TypeScript 源码、转译 logic functions 和 front components把所有产物写入.twenty/output/并生成一份可分发的manifest.json。加上--tarball参数会额外打出一个.tgz包用于手动分发或发布命令。发布前建议先跑一遍与 CI 相同的检查来自 Publishing 教程yarn lint # oxlint yarn typecheck # tsgo yarn test:unit # 单元测试 yarn twenty plan # 预览元数据 diff不实际应用plan只打印会在服务器上产生什么变化、并不应用适合作为发布前的最后一步确认。路径一tarball 部署到服务器适合不希望公开的应用自研工具、企业专属集成、实验性构建。1. 配置指向目标服务器的 remoteremote 保存服务器 URL 和认证凭据存放在本地的~/.twenty/config.json。先添加一个 remote命令中的https://your-twenty-server.com为文档占位地址替换为你的真实服务器 URL--as production指定该 remote 的名称yarn twenty remote:add --url https://your-twenty-server.com --as production在 CI 等无交互环境可加 API key 非交互添加见 CLI 文档yarn twenty remote:add --url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote用yarn twenty remote:list列出已配置的 remote用yarn twenty remote:status检查当前激活 remote 的认证是否仍然有效。2. 部署构建并上传一步完成yarn twenty app:publish --private # 部署到指定 remote # yarn twenty app:publish --private --remote production不带--private的yarn twenty app:publish是发布到 npm--private才是上传 tarball 到服务器的私有注册表。3. 验证与共享在 Twenty UI 的Settings Applications页面可以浏览并安装已部署的应用。tarball 应用不会出现在公开市场同一服务器上的其他 workspace 无法通过浏览发现它。要共享给其他 workspace进入Settings Applications Registrations打开你的应用在Distribution标签点击Copy share link把链接发给其他 workspace 的用户链接直达该应用的安装页share link 使用服务器基础 URL不含 workspace 子域因此对服务器上任意 workspace 都有效。4. 更新版本时的规则更新已部署的 tarball 应用时package.json里的version必须按 semver 排序严格高于当前已部署版本。重复部署同版本或推送更低版本会在 tarball 落盘前被拒绝CLI 报VERSION_ALREADY_EXISTS。发布更新的步骤提升package.json的version例如1.2.3→1.2.4、1.3.0或2.0.0重新执行yarn twenty app:publish --private对已安装该应用且开启了自动升级应用 Settings 标签中的 workspace后台自动升级其余 workspace 会在设置中看到可用升级文档明确了预发布规则1.0.0-rc.1→1.0.0-rc.2是允许的1.0.0会被正确识别为高于1.0.0-rc.5package.json中的 version 本身必须是合法 semver 字符串。5. 声明最低服务器版本可选如果应用用到了某个 Twenty 服务器版本才引入的功能用package.json的engines.twenty声明最低服务器版本该字段同时也是本地yarn twenty docker:start解析镜像版本的依据{ name: twenty-my-app, version: 1.0.0, engines: { node: ^24.5.0, twenty: 2.3.0 } }值是标准 semver 范围2.3.0表示 2.3.0 及以后任意版本^2.3.0等价于2.3.0 3.0.0。行为规则engines.twenty已设置且目标服务器版本不满足范围时部署tarball 上传或安装都会被拒绝报SERVER_VERSION_INCOMPATIBLE错误信息中同时给出要求范围和服务器实际版本未设置engines.twenty时应用在任何服务器版本上都被接受向后兼容服务器未配置APP_VERSION时该检查被跳过。服务器是权威检查方无论是带外部署 tarball 还是从市场安装服务器都会强制校验兼容性。路径二发布到 npm上架 Twenty 市场1. 前置配置一个 npm 账号package.json的keywords数组里加twenty-app—— 这一步需要手动添加create-twenty-app模板默认不包含{ name: twenty-app-postcard-sender, version: 1.0.0, keywords: [twenty-app] }2. 市场元数据可选但影响展示defineApplication()配置中的可选字段控制应用在市场中的展示。logo和galleryImages引用public/目录里的图片export default defineApplication({ universalIdentifier: ..., displayName: My App, description: A great app, logo: public/logo.png, galleryImages: [ public/screenshot-1.png, public/screenshot-2.png, ], });限制与行为市场的galleryImages容器固定为8:5比例例如1600×1000 px。任意比例的图都会完整显示、不会被裁剪但明显偏高或偏窄的图两侧会留空边logo和每个galleryImages文件不得超过10 MB超出的文件在市场重新托管你的发布资产时会被跳过即不会显示未在defineApplication()中定义aboutDescription时市场自动使用 npm 包中的README.md作为 About 页内容想在市场显示不同描述就显式设置aboutDescription。完整字段列表author、category、websiteUrl、termsUrl等见 Application Config 文档 的 Marketplace metadata 一节。3. 发布yarn twenty app:publish # 发布到指定 dist-tag如 beta、next yarn twenty app:publish --tag beta该命令会构建应用并把.twenty/output发布到 npm。4. 触发市场目录同步Twenty 服务器每小时从 npm registry 同步一次市场目录。不想等的话立即触发--remote可指定目标 remoteyarn twenty dev:catalog-sync # yarn twenty dev:catalog-sync --remote production同步完成后市场里显示的元数据即来自你的defineApplication()配置。安装验证两条路径通用应用发布npm或部署tarball后workspace 通过 UI 安装打开 Twenty 的Settings Applications页面市场应用和 tarball 部署的应用都能在此浏览并安装。也可以用命令行yarn twenty app:install服务器在安装时强制 semver 规则与部署规则对应安装与当前已安装相同的版本 → 报APP_ALREADY_INSTALLED安装低于当前已安装版本的版本 → 报CANNOT_DOWNGRADE_APPLICATION要安装更高版本先部署或发布新版本再重新执行yarn twenty app:install排查与限制Registration 归属被拒。发布应用会创建一个 application registration应用在该实例上的身份所有安装它的 workspace 共享。universalIdentifier在整个实例内唯一一个 registration 最多属于一个 workspaceowner。安装和开发是两种不同的权利操作要求安装应用应用已上架市场、被运营者预装、或 registration 属于你的 workspace开发应用yarn twenty dev、apply、planregistration 属于你的 workspace两种情况会导致拒绝identifier 属于另一个 workspace修改应用配置中的universalIdentifier这是 fork 他人应用时的通常做法如需保留原 identifier必须由 owner workspace 把 registration 转移给你。identifier 不属于任何 workspace从市场目录同步导入的应用初始是无主的需要先通过 npm trusted publishing 认领再在其上开发。从私有仓库发布的 provenance 问题。npm 只接受来自公开源码仓库的 provenance。从私有仓库发布时npm 会以E422 ... Unsupported GitHub Actions source repository visibility: private拒绝 OIDC provenance 包。确需从私有仓库发布时在publish.yml发布步骤的env中设置TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: true关闭 provenance。cd.yml 的默认部署地址不可用。模板生成的cd.yml中TWENTY_DEPLOY_URL默认为http://localhost:3000这只是占位值GitHub 托管 runner 无法访问。启用 CD 前必须把它改成你服务器的公网 URL或改用有网络可达性的自托管 runner。可选用模板内置的 CI 自动化create-twenty-app生成的应用在.github/workflows/下自带三个 GitHub Actions 工作流工作流行为需要的配置ci.yml每次 push 到main和每次 PR 跑集成测试启动临时 Twenty 测试实例无 secrets可用TWENTY_VERSIONenv 固定 CI 使用的服务器版本cd.yml每次 push 到main自动执行app:publish --private并安装到目标 workspace给 PR 加deploy标签可触发预览部署env中的TWENTY_DEPLOY_URL Actions Secrets 中具备部署权限的TWENTY_DEPLOY_API_KEYpublish.ymlpush 版本 tag如v1.0.0或在 Actions 页手动触发时发布到 npm带 provenance一次性在 npm 官网该包的 Settings → Trusted Publisher 注册本仓库与publish.yml工作流npm 需 11.5.1publish.yml中无需写 npm 参数CI 里运行yarn twenty app:publish时会自动加上--provenance和--access public。provenance 同时是你在 Twenty 市场中认领应用所有权的方式。其他 CI 系统GitLab CI、CircleCI 等直接yarn install后运行yarn twenty app:publish即可环境能签发 OIDC token 时会输出 provenance否则自动跳过。ci.yml/cd.yml引用的可复用 action 默认指向main需要确定性构建时可把每行uses:改为 commit SHA 或 release tag。相关文档Publishing两条分发路径的完整参考CLIyarn twenty全部命令与 remote 管理Application ConfigdefineApplication()与全部市场元数据字段Quick Start搭建应用与本地开发环境Testing发布前的测试与类型检查【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考