发布与部署指南

引言

发布是模板开发的最后一环，也是将本地成果同步到 AiCms 远端的关键步骤。建议在发布前完成渲染与预览，确保页面与资源完整。

本地预览与检查

发布前先完成渲染与预览，保证输出目录存在且页面无明显问题：

tmaker render tmaker
          tmaker preview tmaker
          tmaker preview tmaker --port 3000

输出结构详解

渲染结果输出到 templates_outputs/<id>，保持与 pages/ 相同的目录结构。确认输出目录完整是发布前的必要步骤。

发布到AiCms详解

基础发布命令：

tmaker publish tmaker

常用参数：

• --name / -n：指定远端模板名称。
• --no-resources / -nr：不上传静态资源。
• --resource-type / -r：仅发布指定资源类型（metadata / page / component / media / categorytree / category）。
• --media-type / -m：仅发布特定媒体类型（如 image / css / javascript / webfonts）。
• --image-path / -ip：仅发布指定图片目录（相对于 image/）。
• --force / -f：强制发布，忽略部分本地优化逻辑。

# 指定远端名称
          tmaker publish tmaker --name tmaker-prod
          
          # 只发布页面
          tmaker publish tmaker --resource-type page
          
          # 只发布图片
          tmaker publish tmaker -r media -m image
          
          # 仅发布 image/blog 目录
          tmaker publish tmaker -r media -m image -ip blog
          

发布前检查清单

• 已完成 tmaker render，输出目录存在。
• 使用 tmaker preview 验证关键页面。
• SEO 文件（.seo.json）完整，链接以 / 结尾。
• 图片与静态资源路径正确，引用未丢失。

版本控制与回滚

建议通过 Git 管理版本：发布前打 tag、保留发布记录，出现问题时可回滚到历史 commit 并重新发布。

CI/CD集成

在 CI 环境中可直接使用环境变量提供 token 与 baseUrl：

- name: Publish
            run: tmaker publish tmaker
            env:
              AiCms__BaseUrl: ${{ secrets.AiCms_BASE_URL }}
              AiCms__Token: ${{ secrets.AiCms_TOKEN }}

生产环境最佳实践

• 大规模变更可先发布 page 或 component 做增量验证。
• 媒体资源可用 --media-type 与 --image-path 精准控制。
• 当本地状态异常时使用 --force。

常见问题排查

• Authentication required：运行 tmaker login 或设置 AiCms__Token。
• 远端名称不一致：使用 --name 指定远端模板名。
• 媒体未上传：确认未使用 --no-resources，或改用 --media-type。

总结

发布流程的核心是“渲染 → 预览 → 发布”。合理使用资源筛选参数可以让发布更稳定、更可控。