从 v0.69 到 v3.13TinaCMS 核心包 tinacms 的演进史与关键能力解析【免费下载链接】tinacmsTinaCMS is the leading open-source headless CMS that supports Markdown and Visual Editing. Your content is stored in your own GitHub repo ❤️项目地址: https://gitcode.com/GitHub_Trending/ti/tinacmsTinaCMS 是开源的 headless CMS内容以 Markdown 形式存储在你自己的 Git 仓库中并支持可视化编辑。本文以仓库中 packages/tinacms/CHANGELOG.md覆盖 v0.69.x 至 v3.13.0为骨架梳理tinacms核心包十余个版本的功能演进媒体管理、编辑工作流、富文本编辑器、无 React 可视化编辑tinacms/bridge、自托管后端与依赖瘦身等。读完本文你将掌握这些版本背后的设计取舍、配置参数与迁移要点并能直接在源码中定位对应实现。一、版本脉络从 iframe 时代到 ESM 与现代前端tinacms是 TinaCMS 的 React 核心包包含管理后台 UIadmin/、富文本编辑器rich-text/、客户端client.ts、unifiedClient/、表单字段与缓存cache.ts等模块。从变更记录可以读出三条清晰的主线模块化收敛tinacms/toolkit被并入tinacmsv1.5.18 的121bd9fc4提交后续又拆分出tinacms/search、tinacms/mdx、tinacms/schema-tools等独立包tinacms通过依赖关系消费它们。构建现代化v3.0.0PR #5982完成 CommonJS → ESM 的迁移v2.0.0 升级 React 18v3.12.1 将final-form系列升级到 TypeScript 重写版react-final-form7首次把 React 19 纳入 peer 范围。前端无关化v3.8.0 推出tinacms/bridge让 Astro、Hugo 甚至纯 HTML 都能获得完整可视化编辑体验不再强制引入 React详见下文第四节。版本依赖更新集中在tinacms/schema-tools、tinacms/mdx、tinacms/search、tinacms/bridge四个包上说明这些是核心包的地基。二、媒体管理从上传/删除到搜索、筛选、重命名与类型限制媒体管理Media Manager是近年迭代最密集的区域v3.12.0 至 v3.13.0 之间完成了一次能力补全。2.1 媒体重命名v3.12.0 引入v3.13.0 支持 TinaCloudv3.12.0PR #7391本地开发模式通过 CLI dev server 新增POST /media/rename路由媒体预览中提供Rename操作。重命名只改 basename、保留扩展名并复用上传时的 sanitize 规则做预览冲突与文件缺失会给出针对性报错。重命名不会更新内容中已引用的旧路径模态框会明确提示。该操作仅在媒体存储实现了rename时才显示——TinaMediaStore本地实现TinaCloud、静态与自托管 repo 媒体存储不暴露S3、Cloudinary、DigitalOcean Spaces、Azure 等第三方存储可通过实现MediaStore.rename主动接入。v3.13.0PR #7423TinaCloud 侧补齐同名能力。仓库型媒体可直接在 Media Manager 中重命名非保护分支直接应用保护分支则走编辑工作流从新工作流分支创建 Pull RequestMediaManager.rename()会派发media:rename:start/success/failure事件。2.2 搜索与文件夹筛选v3.12.0PR #7323Media Manager 新增按文件路径搜索防抖、跨文件夹递归、大小写不敏感与All | Folders | Files视图切换文件带类型徽标JPEG/PNG/MP4…视频有播放覆盖层。本地 dev server 的媒体端点新增search查询参数与无过滤列表共用limit/cursor分页契约。搜索框按MediaStore接口上的searchable标志逐存储选择开启——不声明支持搜索的存储不会得到一个返回未过滤结果的假搜索框。v3.12.0 同时把列表切换到了 v2 assets-api 端点上传/删除仍走 v1为搜索铺路。2.3 图片字段的 accept 限制v3.13.0PR #7477 及其补丁image 字段新增accept属性用于限制可接受的文件类型取值可以是扩展名如jpg、类别image、video、audio、document或两者的数组。行为闭环字段自带 dropzone 与媒体选择器都会拒绝范围外文件选择器会把媒体库收窄到匹配文件越界选择会弹出 alert 而非写入jpg与jpeg视为同一类型已有值不受影响。补丁PR #7477 follow-up把accept正确应用到list: true的图库字段上此前列表项是用裸{component: image}构建的没有任何限制并让本地 dev server 在/media/list上接受ext参数、分页前先行过滤staticMedia存储因无法做扩展名过滤而直接隐藏该控件。从源码结构看相关实现集中在 packages/tinacms/src/toolkit/ 的 media 相关组件与 packages/tinacms/cli/ 的 dev server 路由中。三、编辑工作流分支、Pull Request 与保存选项编辑工作流Editorial Workflow面向内容由非开发者维护、改动经 PR 合入的场景本文件记录了它从粗糙到成熟的全程。3.1 保存选项下拉v3.10.0PR #7138Save changes to new branch 模态框把 draft / ready-for-review 开关升级为保存选项下拉Save draft存草稿、Saveready for review、Save and publish保存并发布。主按钮默认记住编辑器上次的选择默认 draftlocalStorage 记忆保护分支上Save and publish会禁用并显示 tooltip。v3.10.0 还新增了 PR 的 draft / ready-to-review 切换PR #7136v3.13.0 则让保存对话框显示配置的 Git 作者TinaCloud bot 或本人附修改入口链接。3.2 分支名校验与规范化v3.12.1PR #6763Save to new branch 曾因派生分支名不是合法 Git ref 而报Branch operation failed——例如 collection 的path带尾斜杠时产生content/articles//foo.mdx派生 ref 变成非法的tina/articles//foo。现在对默认分支名与用户输入统一规范化重复与首尾斜杠折叠、Git 禁止字符空白、控制字符、~ ^ : ? * [ \ 与{序列替换为连字符、..折叠、按路径段去除前导点与尾部./.lock分支切换器与已删除分支恢复模态框共用同一formatBranchName 工具。此外 v3.4.0 修复了分支存在检测的大小写敏感匹配v2.9.1 修复了保护分支检查时未解码分支名的问题。3.3 性能与可观测性v3.11.0PR #7235编辑工作流保存只做一次分支列表查询替代原来的两次顺序查询进度模态框出现前的延迟约减半。v3.10.0PR #7140新增 PostHogeditorial-workflow-save事件记录使用的保存选项、是否成功与失败原因。v3.9.0PR #6902保护分支上的媒体上传/删除也纳入编辑工作流——提示选分支、写入分支、成功后切换编辑器并走索引与 PR 创建流程PR 标题现在会把分支名中的所有连字符替换为空格。四、无 React 的可视化编辑tinacms/bridgev3.8.0v3.8.0PR #6771是本文件中最具架构意义的一次发布TinaCMS 可视化编辑不再要求 React。此前可视化编辑依赖useTina()这一 React hookAstro 这类默认零 JS的框架只能靠 iframe 内水合 React 来妥协。新发布的 packages/tinacms/bridge/ 是一个约 2 KB gzip、零依赖的 ESM 包直接说现有 admin 的 postMessage 协议head div >import { createDatabase, createLocalDatabase } from tinacms/datalayer; import { MongodbLevel } from mongodb-level; import { GitHubProvider } from tinacms-gitprovider-github; const isLocal process.env.TINA_PUBLIC_IS_LOCAL true; export default isLocal ? createLocalDatabase() : createDatabase({ gitProvider: new GitHubProvider({ branch: process.env.GITHUB_BRANCH, owner: process.env.GITHUB_OWNER, repo: process.env.GITHUB_REPO, token: process.env.GITHUB_PERSONAL_ACCESS_TOKEN, }), databaseAdapter: new MongodbLevelstring, Recordstring, any({ collectionName: tinacms, dbName: tinacms, mongoUri: process.env.MONGODB_URI, }), namespace: process.env.GITHUB_BRANCH, });非 GitHub 场景可实现GitProvider接口onPut(key, value)/onDelete(key)自定义 Git 提供方level到databaseAdapter只是一字之差的重命名createDatabase({ - level: new MongodbLevelstring, Recordstring, any(...), databaseAdapter: new MongodbLevelstring, Recordstring, any(...), })2. 认证迁移admin.auth废弃并重命名为admin.authHooks引入defineConfig的authProvider与可继承的AbstractAuthProvider基类import { AbstractAuthProvider } from tinacms; class CustomAuthProvider extends AbstractAuthProvider { login() {} logout() {} //... } defineConfig({ authProvider: new CustomAuthProvider(), //... });新增 Clerk 认证提供方packages/tinacms-clerk/v3.12.0 还支持 WorkOS 启用时的重定向式认证流程。3. 单函数后端不再把后端托管在/tina/api/gql.ts而是由tinacms/datalayer导出的TinaNodeBackend聚合到单一路由/api/tina/[...routes].{ts,js}import { TinaNodeBackend, LocalBackendAuthProvider, } from tinacms/datalayer; import { TinaAuthJSOptions, AuthJsBackendAuthProvider } from tinacms-authjs; import databaseClient from ../../../tina/__generated__/databaseClient; const isLocal process.env.TINA_PUBLIC_IS_LOCAL true; const handler TinaNodeBackend({ authProvider: isLocal ? LocalBackendAuthProvider() : AuthJsBackendAuthProvider({ authOptions: TinaAuthJSOptions({ databaseClient: databaseClient, secret: process.env.NEXTAUTH_SECRET, }), }), databaseClient, }); export default (req, res) { return handler(req, res); };七、表单与字段配置defaultItem、slugify、beforeSubmit 等实用 API本文件在 v0.69.x–v1.5.x 之间沉淀了一批高频率使用的字段/collection 配置项defaultItemv0.69.12 取代defaultValuecollection 级默认内容可为对象或函数defaultItem: () { const m new Date(); return { title: New Page, test: This is a default value of the test field, filename: new-page-${m.getUTCFullYear()}-${(m.getUTCMonth() 1)}-${m.getUTCDate()}, }; },filename自定义v0.69.12ui.filename.slugify自定义文件命名配合isTitle时自动附加默认 slugifyname: posts, path: content/posts, ui: { filename: { slugify: (values) mySlugifyFunc(values), disabled: true, // label、component、parse 等其他字段属性仍可用 } },v1.5.18 让slugify收到第二个参数当前 collection 与 templatev3.4.0 为 filename 字段增加parsev3.3.2 修复了提供 slugify 方法时只读字段仍可编辑的问题。beforeSubmitv1.5.18collection 的ui.beforeSubmit钩子在表单提交前运行返回的值替代表单值提交返回假值则用原值ui: { beforeSubmit: async ({ values }) { return { ...values, lastUpdated: new Date().toISOString() }; }, },router与globalv0.69.5ui.router取代 RouteMapper 插件ui.global: true取代大部分formifyCallback场景。allowedActionsv0.70.2按 collection 关闭创建/删除按钮ui.allowedActions: { create: false, delete: false }配合单文档 collection 时 v1.4.2 会直接跳转文档编辑页。addItemBehaviorv2.8.2lists/groups 新增项的位置可选prepend或append。openFormOnCreatev3.6.0object 字段新建时自动进入内部表单。displayOnlyv3.7.3只读展示型字段类型v3.12.1 还为 list/group-list/blocks 字段补充了data-test钩子如data-testadd-item-blocks.0.actions供 e2e 测试稳定定位控件。引用完整性v2.5.0重命名文档时自动更新所有引用它的文档删除时给出警告并级联删除引用。富文本渲染兜底v0.69.0未知 JSX/HTML 不再报错回退为No component provided for component namemarkdown 解析错误回退为字符串渲染可通过TinaMarkdown的invalid_markdownprop 定制。八、稳定性、会话与安全加固近年 patch 集中在会话过期后 admin 不崩、不误导上v3.13.0PR #7486会话编辑中途过期时所有路径都回到登录模态框。GraphQL 请求 401 时 content API client 派发cms:session-expired并抛出类型化的SessionExpiredErrorREST 传输分支列表、计费、编辑工作流轮询、搜索索引、媒体存储同样通知该流程避免假保存成功 toast与误导性的未授权面板。认证墙在过期与重新登录之间抑制新 alert会话过期不再被记为保存失败顺带修复了registerApi事件桥中api.events从未真正送达全局总线的历史缺陷。v3.12.1PR #7483 / #7445会话检查失败时GetCollection/GetDocument不再向子组件传undefined曾导致整页被 TypeError 卡片替换无 token 时跳过 identity 请求、避免误导性 401/CORS 报错。v3.9.1PR #7028文件系统回退响应缓存在 edge runtimeCloudflare Workers、Vercel Edge上自动跳过createClient新增cache选项可强制关闭。v3.10.0PR #7143文件夹名校验与文档文件名/后端relativePath白名单统一允许列表位于tinacms/schema-tools单一共享常量folderNameRegex叠加在基线之上v3.7.3 起relativePath拒绝空白与非法字符。九、依赖与包体瘦身数据可复验的优化记录本文件非常难得地记录了每次依赖清理的量化收益这些数字可以直接作为性能优化的参考资料v3.12.0图标库收敛到lucide-react约 -85 MB删除react-icons84 MB与heroicons/react删除headlessui/react约 -50 MB11 个文件改用 Radix停止随包发布monaco-editor约 -73 MB编辑器一直由monaco-editor/loader从 CDN 运行时加载版本 0.55.1 与锁定的 0.31.0 本就不一致。v3.12.1移除crypto-js依赖CLI 用node:crypto的randomBytes(16).toString(hex)生成默认NEXTAUTH_SECRET输出仍是 32 字符十六进制串。v3.9.4moment-timezone移入 devDependencies约 -39 KB gzip日期处理统一到 date-fns移除moment/react-datetime栈约 -18.6 KB gzip并通过非破坏性的 moment→date-fns token 转换器保证旧dateFormat/timeFormat的 moment 语法继续可用。v3.12.0PR #7233tinacms/mdx/sanitize-url子路径导出只含约 15 行的 URL scheme 净化器TinaMarkdown/StaticTinaMarkdown不再因导入sanitizeUrl而拖入约 2 MB 的 remark/mdast/micromark 解析包。v3.11.0PR #7213内部依赖从workspace:*发布时展开为精确版本改为workspace:^发布为 caret 范围。此前精确 pin 无法与消费者已装版本去重一个标准 Astro TinaCMS 博客会出现三份tinacms、三份mermaid186 MB、五份date-fns151 MB与四份typescript88 MB合计约320 MB 重复改为范围依赖后正常去重也让next-tinacms-cloudinary等 peer 依赖tinacms的包不再因精确版本引发ERESOLVE冲突。v3.0.2tinacms/graphql移除scmp、tinacms/metrics移除isomorphic-fetch改用全局 fetch、CLI 移除log4js并升级 chalk v5ESM-only。十、升级提示与破坏性变更汇总对照本文件升级到新版本时最需要留意的破坏性点如下版本变更影响v3.13.0Markdown 表格渲染thead/th移除表格默认内联样式需更新按td/首行选择器的样式自行补充表格边框v3.8.0tinacms/astro迁移路径、tinacms/bridge新包非 React 前端改用 bridgeuseTina()仍可用v3.7.0mark成为保留的 MDX 组件名高亮功能自定义mark模板需改名v3.0.0全面迁移 ESMCJS 消费者需调整导入方式v2.7.2MarkToolbarButton不再导出使用方需替换v2.6.0toolbarOverride弃用改用overrides.toolbarv1.5.24createDatabase参数重构、admin.auth→admin.authHooks/authProvider自托管用户需按上文迁移database.ts与认证配置v1.5.18tinacms/toolkit并入tinacms直接依赖 toolkit 的导入路径变化v0.70.0staticConfig→defineConfig、defineConfig→defineLegacyConfig配置入口改名结语与延伸阅读tinacms的这份变更记录本质上是一部面向 Git 内容仓库的 React CMS 如何走向现代前端的技术编年史媒体管理从基本上传演进为可搜索、可筛选、可重命名、可限类型的完整资产库编辑工作流从建分支PR打磨出 draft/ready/publish 三态与稳健的分支名校验可视化编辑借tinacms/bridge摆脱了 React 的绑定自托管后端收敛为单一TinaNodeBackend函数每一次依赖清理都有精确到字节/兆字节的量化收益。想继续深入这些能力的源码实现推荐阅读packages/tinacms/bridge/无 React 可视化编辑的核心含 forms.ts、preview.ts 与测试 forms.test.tsexamples/astro/visual-editing/bridge 的完整参考实现含 e2e/bridge.spec.tspackages/tinacms/src/rich-text/富文本编辑器相关实现packages/tinacms/src/client.ts 与 packages/tinacms/src/cache.ts客户端与缓存逻辑含 edge runtime 缓存开关配套包的变更记录tinacms/mdx、tinacms/schema-tools、tinacms/search、tinacms/bridge它们与tinacms的版本联动可在各版本的 Updated dependencies 段逐条核对。【免费下载链接】tinacmsTinaCMS is the leading open-source headless CMS that supports Markdown and Visual Editing. Your content is stored in your own GitHub repo ❤️项目地址: https://gitcode.com/GitHub_Trending/ti/tinacms创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从 v0.69 到 v3.13：TinaCMS 核心包 tinacms 的演进史与关键能力解析
从 v0.69 到 v3.13TinaCMS 核心包 tinacms 的演进史与关键能力解析【免费下载链接】tinacmsTinaCMS is the leading open-source headless CMS that supports Markdown and Visual Editing. Your content is stored in your own GitHub repo ❤️项目地址: https://gitcode.com/GitHub_Trending/ti/tinacmsTinaCMS 是开源的 headless CMS内容以 Markdown 形式存储在你自己的 Git 仓库中并支持可视化编辑。本文以仓库中 packages/tinacms/CHANGELOG.md覆盖 v0.69.x 至 v3.13.0为骨架梳理tinacms核心包十余个版本的功能演进媒体管理、编辑工作流、富文本编辑器、无 React 可视化编辑tinacms/bridge、自托管后端与依赖瘦身等。读完本文你将掌握这些版本背后的设计取舍、配置参数与迁移要点并能直接在源码中定位对应实现。一、版本脉络从 iframe 时代到 ESM 与现代前端tinacms是 TinaCMS 的 React 核心包包含管理后台 UIadmin/、富文本编辑器rich-text/、客户端client.ts、unifiedClient/、表单字段与缓存cache.ts等模块。从变更记录可以读出三条清晰的主线模块化收敛tinacms/toolkit被并入tinacmsv1.5.18 的121bd9fc4提交后续又拆分出tinacms/search、tinacms/mdx、tinacms/schema-tools等独立包tinacms通过依赖关系消费它们。构建现代化v3.0.0PR #5982完成 CommonJS → ESM 的迁移v2.0.0 升级 React 18v3.12.1 将final-form系列升级到 TypeScript 重写版react-final-form7首次把 React 19 纳入 peer 范围。前端无关化v3.8.0 推出tinacms/bridge让 Astro、Hugo 甚至纯 HTML 都能获得完整可视化编辑体验不再强制引入 React详见下文第四节。版本依赖更新集中在tinacms/schema-tools、tinacms/mdx、tinacms/search、tinacms/bridge四个包上说明这些是核心包的地基。二、媒体管理从上传/删除到搜索、筛选、重命名与类型限制媒体管理Media Manager是近年迭代最密集的区域v3.12.0 至 v3.13.0 之间完成了一次能力补全。2.1 媒体重命名v3.12.0 引入v3.13.0 支持 TinaCloudv3.12.0PR #7391本地开发模式通过 CLI dev server 新增POST /media/rename路由媒体预览中提供Rename操作。重命名只改 basename、保留扩展名并复用上传时的 sanitize 规则做预览冲突与文件缺失会给出针对性报错。重命名不会更新内容中已引用的旧路径模态框会明确提示。该操作仅在媒体存储实现了rename时才显示——TinaMediaStore本地实现TinaCloud、静态与自托管 repo 媒体存储不暴露S3、Cloudinary、DigitalOcean Spaces、Azure 等第三方存储可通过实现MediaStore.rename主动接入。v3.13.0PR #7423TinaCloud 侧补齐同名能力。仓库型媒体可直接在 Media Manager 中重命名非保护分支直接应用保护分支则走编辑工作流从新工作流分支创建 Pull RequestMediaManager.rename()会派发media:rename:start/success/failure事件。2.2 搜索与文件夹筛选v3.12.0PR #7323Media Manager 新增按文件路径搜索防抖、跨文件夹递归、大小写不敏感与All | Folders | Files视图切换文件带类型徽标JPEG/PNG/MP4…视频有播放覆盖层。本地 dev server 的媒体端点新增search查询参数与无过滤列表共用limit/cursor分页契约。搜索框按MediaStore接口上的searchable标志逐存储选择开启——不声明支持搜索的存储不会得到一个返回未过滤结果的假搜索框。v3.12.0 同时把列表切换到了 v2 assets-api 端点上传/删除仍走 v1为搜索铺路。2.3 图片字段的 accept 限制v3.13.0PR #7477 及其补丁image 字段新增accept属性用于限制可接受的文件类型取值可以是扩展名如jpg、类别image、video、audio、document或两者的数组。行为闭环字段自带 dropzone 与媒体选择器都会拒绝范围外文件选择器会把媒体库收窄到匹配文件越界选择会弹出 alert 而非写入jpg与jpeg视为同一类型已有值不受影响。补丁PR #7477 follow-up把accept正确应用到list: true的图库字段上此前列表项是用裸{component: image}构建的没有任何限制并让本地 dev server 在/media/list上接受ext参数、分页前先行过滤staticMedia存储因无法做扩展名过滤而直接隐藏该控件。从源码结构看相关实现集中在 packages/tinacms/src/toolkit/ 的 media 相关组件与 packages/tinacms/cli/ 的 dev server 路由中。三、编辑工作流分支、Pull Request 与保存选项编辑工作流Editorial Workflow面向内容由非开发者维护、改动经 PR 合入的场景本文件记录了它从粗糙到成熟的全程。3.1 保存选项下拉v3.10.0PR #7138Save changes to new branch 模态框把 draft / ready-for-review 开关升级为保存选项下拉Save draft存草稿、Saveready for review、Save and publish保存并发布。主按钮默认记住编辑器上次的选择默认 draftlocalStorage 记忆保护分支上Save and publish会禁用并显示 tooltip。v3.10.0 还新增了 PR 的 draft / ready-to-review 切换PR #7136v3.13.0 则让保存对话框显示配置的 Git 作者TinaCloud bot 或本人附修改入口链接。3.2 分支名校验与规范化v3.12.1PR #6763Save to new branch 曾因派生分支名不是合法 Git ref 而报Branch operation failed——例如 collection 的path带尾斜杠时产生content/articles//foo.mdx派生 ref 变成非法的tina/articles//foo。现在对默认分支名与用户输入统一规范化重复与首尾斜杠折叠、Git 禁止字符空白、控制字符、~ ^ : ? * [ \ 与{序列替换为连字符、..折叠、按路径段去除前导点与尾部./.lock分支切换器与已删除分支恢复模态框共用同一formatBranchName 工具。此外 v3.4.0 修复了分支存在检测的大小写敏感匹配v2.9.1 修复了保护分支检查时未解码分支名的问题。3.3 性能与可观测性v3.11.0PR #7235编辑工作流保存只做一次分支列表查询替代原来的两次顺序查询进度模态框出现前的延迟约减半。v3.10.0PR #7140新增 PostHogeditorial-workflow-save事件记录使用的保存选项、是否成功与失败原因。v3.9.0PR #6902保护分支上的媒体上传/删除也纳入编辑工作流——提示选分支、写入分支、成功后切换编辑器并走索引与 PR 创建流程PR 标题现在会把分支名中的所有连字符替换为空格。四、无 React 的可视化编辑tinacms/bridgev3.8.0v3.8.0PR #6771是本文件中最具架构意义的一次发布TinaCMS 可视化编辑不再要求 React。此前可视化编辑依赖useTina()这一 React hookAstro 这类默认零 JS的框架只能靠 iframe 内水合 React 来妥协。新发布的 packages/tinacms/bridge/ 是一个约 2 KB gzip、零依赖的 ESM 包直接说现有 admin 的 postMessage 协议head div >import { createDatabase, createLocalDatabase } from tinacms/datalayer; import { MongodbLevel } from mongodb-level; import { GitHubProvider } from tinacms-gitprovider-github; const isLocal process.env.TINA_PUBLIC_IS_LOCAL true; export default isLocal ? createLocalDatabase() : createDatabase({ gitProvider: new GitHubProvider({ branch: process.env.GITHUB_BRANCH, owner: process.env.GITHUB_OWNER, repo: process.env.GITHUB_REPO, token: process.env.GITHUB_PERSONAL_ACCESS_TOKEN, }), databaseAdapter: new MongodbLevelstring, Recordstring, any({ collectionName: tinacms, dbName: tinacms, mongoUri: process.env.MONGODB_URI, }), namespace: process.env.GITHUB_BRANCH, });非 GitHub 场景可实现GitProvider接口onPut(key, value)/onDelete(key)自定义 Git 提供方level到databaseAdapter只是一字之差的重命名createDatabase({ - level: new MongodbLevelstring, Recordstring, any(...), databaseAdapter: new MongodbLevelstring, Recordstring, any(...), })2. 认证迁移admin.auth废弃并重命名为admin.authHooks引入defineConfig的authProvider与可继承的AbstractAuthProvider基类import { AbstractAuthProvider } from tinacms; class CustomAuthProvider extends AbstractAuthProvider { login() {} logout() {} //... } defineConfig({ authProvider: new CustomAuthProvider(), //... });新增 Clerk 认证提供方packages/tinacms-clerk/v3.12.0 还支持 WorkOS 启用时的重定向式认证流程。3. 单函数后端不再把后端托管在/tina/api/gql.ts而是由tinacms/datalayer导出的TinaNodeBackend聚合到单一路由/api/tina/[...routes].{ts,js}import { TinaNodeBackend, LocalBackendAuthProvider, } from tinacms/datalayer; import { TinaAuthJSOptions, AuthJsBackendAuthProvider } from tinacms-authjs; import databaseClient from ../../../tina/__generated__/databaseClient; const isLocal process.env.TINA_PUBLIC_IS_LOCAL true; const handler TinaNodeBackend({ authProvider: isLocal ? LocalBackendAuthProvider() : AuthJsBackendAuthProvider({ authOptions: TinaAuthJSOptions({ databaseClient: databaseClient, secret: process.env.NEXTAUTH_SECRET, }), }), databaseClient, }); export default (req, res) { return handler(req, res); };七、表单与字段配置defaultItem、slugify、beforeSubmit 等实用 API本文件在 v0.69.x–v1.5.x 之间沉淀了一批高频率使用的字段/collection 配置项defaultItemv0.69.12 取代defaultValuecollection 级默认内容可为对象或函数defaultItem: () { const m new Date(); return { title: New Page, test: This is a default value of the test field, filename: new-page-${m.getUTCFullYear()}-${(m.getUTCMonth() 1)}-${m.getUTCDate()}, }; },filename自定义v0.69.12ui.filename.slugify自定义文件命名配合isTitle时自动附加默认 slugifyname: posts, path: content/posts, ui: { filename: { slugify: (values) mySlugifyFunc(values), disabled: true, // label、component、parse 等其他字段属性仍可用 } },v1.5.18 让slugify收到第二个参数当前 collection 与 templatev3.4.0 为 filename 字段增加parsev3.3.2 修复了提供 slugify 方法时只读字段仍可编辑的问题。beforeSubmitv1.5.18collection 的ui.beforeSubmit钩子在表单提交前运行返回的值替代表单值提交返回假值则用原值ui: { beforeSubmit: async ({ values }) { return { ...values, lastUpdated: new Date().toISOString() }; }, },router与globalv0.69.5ui.router取代 RouteMapper 插件ui.global: true取代大部分formifyCallback场景。allowedActionsv0.70.2按 collection 关闭创建/删除按钮ui.allowedActions: { create: false, delete: false }配合单文档 collection 时 v1.4.2 会直接跳转文档编辑页。addItemBehaviorv2.8.2lists/groups 新增项的位置可选prepend或append。openFormOnCreatev3.6.0object 字段新建时自动进入内部表单。displayOnlyv3.7.3只读展示型字段类型v3.12.1 还为 list/group-list/blocks 字段补充了data-test钩子如data-testadd-item-blocks.0.actions供 e2e 测试稳定定位控件。引用完整性v2.5.0重命名文档时自动更新所有引用它的文档删除时给出警告并级联删除引用。富文本渲染兜底v0.69.0未知 JSX/HTML 不再报错回退为No component provided for component namemarkdown 解析错误回退为字符串渲染可通过TinaMarkdown的invalid_markdownprop 定制。八、稳定性、会话与安全加固近年 patch 集中在会话过期后 admin 不崩、不误导上v3.13.0PR #7486会话编辑中途过期时所有路径都回到登录模态框。GraphQL 请求 401 时 content API client 派发cms:session-expired并抛出类型化的SessionExpiredErrorREST 传输分支列表、计费、编辑工作流轮询、搜索索引、媒体存储同样通知该流程避免假保存成功 toast与误导性的未授权面板。认证墙在过期与重新登录之间抑制新 alert会话过期不再被记为保存失败顺带修复了registerApi事件桥中api.events从未真正送达全局总线的历史缺陷。v3.12.1PR #7483 / #7445会话检查失败时GetCollection/GetDocument不再向子组件传undefined曾导致整页被 TypeError 卡片替换无 token 时跳过 identity 请求、避免误导性 401/CORS 报错。v3.9.1PR #7028文件系统回退响应缓存在 edge runtimeCloudflare Workers、Vercel Edge上自动跳过createClient新增cache选项可强制关闭。v3.10.0PR #7143文件夹名校验与文档文件名/后端relativePath白名单统一允许列表位于tinacms/schema-tools单一共享常量folderNameRegex叠加在基线之上v3.7.3 起relativePath拒绝空白与非法字符。九、依赖与包体瘦身数据可复验的优化记录本文件非常难得地记录了每次依赖清理的量化收益这些数字可以直接作为性能优化的参考资料v3.12.0图标库收敛到lucide-react约 -85 MB删除react-icons84 MB与heroicons/react删除headlessui/react约 -50 MB11 个文件改用 Radix停止随包发布monaco-editor约 -73 MB编辑器一直由monaco-editor/loader从 CDN 运行时加载版本 0.55.1 与锁定的 0.31.0 本就不一致。v3.12.1移除crypto-js依赖CLI 用node:crypto的randomBytes(16).toString(hex)生成默认NEXTAUTH_SECRET输出仍是 32 字符十六进制串。v3.9.4moment-timezone移入 devDependencies约 -39 KB gzip日期处理统一到 date-fns移除moment/react-datetime栈约 -18.6 KB gzip并通过非破坏性的 moment→date-fns token 转换器保证旧dateFormat/timeFormat的 moment 语法继续可用。v3.12.0PR #7233tinacms/mdx/sanitize-url子路径导出只含约 15 行的 URL scheme 净化器TinaMarkdown/StaticTinaMarkdown不再因导入sanitizeUrl而拖入约 2 MB 的 remark/mdast/micromark 解析包。v3.11.0PR #7213内部依赖从workspace:*发布时展开为精确版本改为workspace:^发布为 caret 范围。此前精确 pin 无法与消费者已装版本去重一个标准 Astro TinaCMS 博客会出现三份tinacms、三份mermaid186 MB、五份date-fns151 MB与四份typescript88 MB合计约320 MB 重复改为范围依赖后正常去重也让next-tinacms-cloudinary等 peer 依赖tinacms的包不再因精确版本引发ERESOLVE冲突。v3.0.2tinacms/graphql移除scmp、tinacms/metrics移除isomorphic-fetch改用全局 fetch、CLI 移除log4js并升级 chalk v5ESM-only。十、升级提示与破坏性变更汇总对照本文件升级到新版本时最需要留意的破坏性点如下版本变更影响v3.13.0Markdown 表格渲染thead/th移除表格默认内联样式需更新按td/首行选择器的样式自行补充表格边框v3.8.0tinacms/astro迁移路径、tinacms/bridge新包非 React 前端改用 bridgeuseTina()仍可用v3.7.0mark成为保留的 MDX 组件名高亮功能自定义mark模板需改名v3.0.0全面迁移 ESMCJS 消费者需调整导入方式v2.7.2MarkToolbarButton不再导出使用方需替换v2.6.0toolbarOverride弃用改用overrides.toolbarv1.5.24createDatabase参数重构、admin.auth→admin.authHooks/authProvider自托管用户需按上文迁移database.ts与认证配置v1.5.18tinacms/toolkit并入tinacms直接依赖 toolkit 的导入路径变化v0.70.0staticConfig→defineConfig、defineConfig→defineLegacyConfig配置入口改名结语与延伸阅读tinacms的这份变更记录本质上是一部面向 Git 内容仓库的 React CMS 如何走向现代前端的技术编年史媒体管理从基本上传演进为可搜索、可筛选、可重命名、可限类型的完整资产库编辑工作流从建分支PR打磨出 draft/ready/publish 三态与稳健的分支名校验可视化编辑借tinacms/bridge摆脱了 React 的绑定自托管后端收敛为单一TinaNodeBackend函数每一次依赖清理都有精确到字节/兆字节的量化收益。想继续深入这些能力的源码实现推荐阅读packages/tinacms/bridge/无 React 可视化编辑的核心含 forms.ts、preview.ts 与测试 forms.test.tsexamples/astro/visual-editing/bridge 的完整参考实现含 e2e/bridge.spec.tspackages/tinacms/src/rich-text/富文本编辑器相关实现packages/tinacms/src/client.ts 与 packages/tinacms/src/cache.ts客户端与缓存逻辑含 edge runtime 缓存开关配套包的变更记录tinacms/mdx、tinacms/schema-tools、tinacms/search、tinacms/bridge它们与tinacms的版本联动可在各版本的 Updated dependencies 段逐条核对。【免费下载链接】tinacmsTinaCMS is the leading open-source headless CMS that supports Markdown and Visual Editing. Your content is stored in your own GitHub repo ❤️项目地址: https://gitcode.com/GitHub_Trending/ti/tinacms创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考