# @bygghammar/cms-platform 中文文档 规范地址：https://npmcn.com/package/%40bygghammar/cms-platform/ 版本：0\.102\.0 npm 元数据更新时间：2026-10-31T16:01:50.599Z 中文译文更新时间：2026-10-31T17:54:15.276Z 软件包许可：UNLICENSED 本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40bygghammar/cms-platform 原文对照：https://npmcn.com/package/%40bygghammar/cms-platform/?lang=original 项目主页：https://github.com/byggis79/cms-platform#readme 源码仓库：https://github.com/byggis79/cms-platform ## 关键信息（来自 npm 元数据） - 包体积（解压后）：3.6 MB，397 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：1 个 - peer 依赖：zod \>=4\.6\.6 \<5，react \>=19，sonner \>=2，react-dom \>=19，@tiptap/pm \>=3，lucide-react \>=0\.5\.0，@dnd-kit/core \>=6，@tiptap/react \>=3，@dnd-kit/sortable \>=3，@dnd-kit/utilities \>=3，@tiptap/extensions \>=3，@tiptap/starter-kit \>=3，@supabase/supabase-js \>=2，@tanstack/react-query \>=5，@tanstack/react-start \>=1，@tanstack/react-router \>=1，@tiptap/extension-image \>=3，@tiptap/extension-table \>=3，@tiptap/extension-highlight \>=3，@tiptap/extension-subscript \>=3，@tiptap/extension-text-align \>=3，@tiptap/extension-text-style \>=3，@bygghammar/lightweight-popup \>=0\.2\.0-m7\.10，@tiptap/extension-superscript \>=3 - 首次发布：2026-08-12T19:49:49.479Z - 最新版本发布：2026-10-31T16:01:50.411Z - 已发布版本数：131（近 12 个月 131 个） ## 中文简介 共享CMS平台：每个Bygghammar/Voyara站点使用的块，块类型，i18n核心，UI原语和设计令牌合约。 ## 安装 ```sh npm install @bygghammar/cms-platform ``` 也可以使用：`pnpm add @bygghammar/cms-platform`、`yarn add @bygghammar/cms-platform`、`bun add @bygghammar/cms-platform` ## README # @bygghammar / cms-platform 共享CMS平台代码的每个网站在这个工作空间(Voyara， barskola和 未来的网站)。 **代码只** -没有内容，没有数据，没有秘密，没有主题。 ## 这里住着什么？ - `src/blocks/types.ts` -块道具类型和块道具的JSON契约 - `src/blocks/icons.ts` -图标集块可以参考 - `src/blocks/block-props-context.tsx` -块道具管道内联编辑 - `src/i18n/*` 本地化核心（locale, types, resolver, context） - `src/backup/*` -存档/媒体安全，浏览器端大型媒体导出和 与提供者无关的验证帮助程序 - `src/trips/*` -可重用的旅行数据合同、编辑器和遗留课程数据 兼容性。每个主机提供自己的术语(课程，巡航或 旅行)。 - `src/navigation/*` -公共和后台导航合同加上共享 活动状态的帮手。菜单内容和可视标题保留在每个站点上。 - `src/theme.css` -设计代币合约+中立启动主题 ## 开始一个新站点 `docs/NEW-SITE.md` 是支持的启动器路径：install， assert合同， 应用规范模式 `bunx cms-platform-migrations`、进口 `theme.css`，注册主机组件/平台数据/翻译，封装 服务器内核和挂载共享的后台视图。 ## 编辑锁 `docs/EDIT-LOCKS.md` 是什么使一台主机连接两个管理员不能 相互覆盖：运行迁移，通过公开一个服务器端点 `editLockActionCore`,山 `EditLockProvider` 与 `createEditLockApi`, 向前 `editSessionId` 为救球干杯。在此之前，每个屏幕都是正常的 就像锁出现之前一样。 ## 功能指南 | 指南 | 它涵盖了什么 | | --- | --- | | `docs/PAGES.md` | 草稿/发布页面，发布和取消发布确认，复制 | | `docs/SCHEDULING.md` | `VisibilitySchedule`，网站时区编辑，计划菜单和页脚项目 | | `docs/LAYOUT-BLOCKS.md` | 列块，嵌套块树及其移动规则，图标卡移动旋转木马 | | `docs/IMAGE-CARDS.md` | 图像卡画廊块：它的道具，默认值，覆盖和颜色规则，链接，电话滑块和编辑器 | | `docs/MEDIA-FOLDERS.md` | 自动月文件夹，自定义上传文件夹及其消毒，库浏览 | | `docs/GOOGLE-SHEETS.md` | 服务帐户表单交付、连接测试以及所需的服务器变量 | | `docs/TYPOGRAPHY.md` | 独立的谷歌字体用于菜单和页脚 | | `docs/PUBLICATION-REVIEW.md` | 这个 `cms-review` 运行站点升级到精简v3版本的操作步骤 | ## 服务器变量 除了现有的提供程序秘密之外，谷歌Sheets的交付也可以读取 `GOOGLE_SERVICE_ACCOUNT_JSON`，或者 `GOOGLE_SERVICE_ACCOUNT_EMAIL` 加上 `GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY`． 这三个都是服务器专用的；没有谷歌 在浏览器中从未读取过相关的内容，字体选择器不需要API键。看到 `docs/GOOGLE-SHEETS.md`. ## 兼容性策略 - `CHANGELOG.md` 记录每次发布；升级前请阅读。 - pre - 1.0 **小** 发布可能会破坏共享视图、适配器或核心；补丁 版本总是兼容的。 - `PLATFORM_CONTRACT_VERSION` （`platform/contract`)在共享时被撞 屏幕启动需要旧站点所缺乏的模式或适配器功能。 网站将其固定在测试中。它是 **v3**：页面保存，发布，垃圾和 恢复通过数据库函数（v2），一个版本记录了五个 它过去用一句话断言的事实——迁移应用，模式 能力，发布扫描，决策应用，路由激活，共五项 分开的记录，后者拒绝在没有前者的情况下写入 (v3)。直接从上一个pre-v2发布的软件包升级， `0.90.0-m7.12`，意味着应用所有五个新的规范化迁移，在 时间顺序排列: 1. `20260904090000_c54603f8-a155-40f8-a86c-54434aa5c0ae.sql` 2. `20260904140000_9f2a7c41-06d5-4d6b-8b4e-1c7a5d3e9b20.sql` 3. `20260904160000_0d565000-2839-4738-aacc-537d7090398f.sql` 4. `20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24.sql` 5. `20261030120000_46a4febc-227e-42ec-bbe3-a0ae9c97feaa.sql` 文件2和文件3是建立合约v2发布的一对文件 行为，但第一个也是规范模式，所以只应用这对 仍 `missingMigrations` 和 `compareSchema` 报告漂移。文件4 添加合同v3：发布分类账、评审模型、路由声明，一个 锁顺序每个页的突变遵循，和复制作为一个单一 事务。它取代了签名处的五个发布功能机构 他们已经有了，没有改变任何一个人的决定，所以没有a 参观者看到了今天的变化。文件5属于无合同版本：它给出 `block_templates` 它自己的时间戳触发器代替触发它的页面 被创建，它分配了一个 `updated_by` 表中没有的列 每次更新模板都失败了。 在部署v3包之前应用它们，然后分别进行验证： `missingMigrations(applied)` 报告没有丢失， **和** `assertPlatformContract(3)` 传球。第二种方法只比较版本号 在网站本身的代码中，从不读取数据库，所以它是不可替代的 首先。 `docs/NEW-SITE.md` 给出完整的命令。 - `migrations/` 仅为模式。网站内容，SEO副本和种子永远不属于 在那里。 ## 什么东西绝对不能住在这里 - 特定站点使用的颜色、字体或间距值(参见 `theme.css`） - 页面内容，SEO文案，媒体，CMS页面JSON - Supabase生成的类型、认证用户、秘密、API密钥 - 路由文件和每个站点部署配置 - 实际的导航链接、公共页签、品牌特定的标题或菜单样式 - 站点表列表，导入顺序，数据库客户端，身份验证和RLS 政策;每个主机向共享备份核心提供这些适配器 ## 备份的核心 该包拥有cms范围的、与提供商无关的备份和恢复部分： - 媒体签名/路径验证和秘密清理 - 将大型媒体文件流式传输到经过身份验证的浏览器中的存档中 - 存档进度和清单合同 - 行计数、用户/角色和媒体验证助手 浏览器媒体导出程序接受仅带有的主机存储适配器 `list()` 和 `download()` 方法加上主机期望的存档格式/模式 版本。将动态导入保存在文件后面 `import.meta.env.SSR` SSR守卫 应用程序，因此仅浏览器的邮政编码无法进入优化的服务器 块图。 在停止导出之前，将重试单个媒体下载。公共 介质桶适配器也应该回退到对象的公共URL 经过身份验证的存储下载失败，因此一个临时大文件请求 不能丢弃其他有效的存档。 消费站点仍然负责其数据集组、表导入 订单，Supabase客户端，超级管理员授权，HTTP路由，审计记录 以及数据库迁移。该包从不包含站点数据或凭据。 ## 一个网站连接 翻译数据是每个站点的内容，因此每个站点一次注册自己的地图 在启动时: ```ts import { registerTranslations } from "@bygghammar/cms-platform/i18n"; registerTranslations({ generated: TRANSLATIONS, overrides: TRANSLATION_OVERRIDES }); ``` 主机组件必须参与应用程序实际使用的值。 不要只依靠 `import "./register-host"` 因为优化的构建可能会 删除该模块时，应用程序的 `package.json` 声明 `"sideEffects": false`. ```tsx import { initializeHostComponents, type HostComponents } from "@bygghammar/cms-platform/host"; const HOST_COMPONENTS = { FocalImage, LazyVideo, FocusPicker, RichTextEditor, mediaLibraryQueryOptions, useMediaUpload, } satisfies Partial; export const BLOCK_REGISTRY = initializeHostComponents(HOST_COMPONENTS, () => createBlockRegistry(), ); ``` 将现有的注册模块保留在消费应用程序的注册模块中 `sideEffects` Allowlist作为深度防御，直到每个入口点都使用 明确的合同。CSS也必须留在allowlist中。 ## 存储库、开发和发布 真理的权威来源是 [https://github.com/byggis79/cms-platform](https://github.com/byggis79/cms-platform) (私人)。这个存储库是独立的——它不再是目录中的目录 站点存储库，并且永远不能将其复制回消费站点。 ```bash bun install bun run check # typecheck + tests + package verification ``` 该包附带TypeScript源文件；没有构建输出。每一个变化 通过拉取请求，每次释放都是通过推 `vX.Y.Z` 匹配的标签 `package.json`． 标签运行 `.github/workflows/publish.yml`，它使用 **信任 出版**GitHub生成一个短期的OIDC令牌，作用域为单个 工作流运行后，NPM通过包的属性来交换发布权限 可信发布服务器配置。没有长期的npm证书参与-没有 `NPM_TOKEN`,没有 `NODE_AUTH_TOKEN`，没有OTP。 [RELEASING.md](https://npmcn.com/package/%40bygghammar/cms-platform/RELEASING.md) 是 工作流检查和NPM设置必须匹配的内容。从来没有发布 手动。 看到 [CONTRIBUTING.md](https://npmcn.com/package/%40bygghammar/cms-platform/CONTRIBUTING.md) 获取完整的工作流程和变更日志 约定。用户安装一个明确的发布版本，例如 `@bygghammar/cms-platform@0.78.0`. ## 常见问题 ### @bygghammar/cms-platform 是什么？ 共享CMS平台：每个Bygghammar/Voyara站点使用的块，块类型，i18n核心，UI原语和设计令牌合约。 ### 如何安装 @bygghammar/cms-platform？ 在项目目录运行 npm install @bygghammar/cms-platform，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（\>=4\.6\.6 \<5）、react（\>=19）、sonner（\>=2）、react-dom（\>=19）、lucide-react（\>=0\.5\.0）、@dnd-kit/core（\>=6）、@dnd-kit/sortable（\>=3）、@dnd-kit/utilities（\>=3）、@tanstack/react-query（\>=5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 cms-review、create-cms-site、cms-platform-migrations，可以用 npx cms-review 直接运行。 ### @bygghammar/cms-platform 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bygghammar\_\_cms-platform 是否存在。 ### @bygghammar/cms-platform 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @bygghammar/cms-platform 可以商用吗？ @bygghammar/cms-platform 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。 ### @bygghammar/cms-platform 还在维护吗？ 最新版本 0\.102\.0 发布于 2026/11/01（2 天前）；至今共发布 131 个版本，其中过去 12 个月发布了 131 个；首次发布于 2026/08/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。