模板目录结构与关键文件
3m45s
引言
清晰的项目结构是大型模板开发的基石。TMaker精心设计了一套目录组织规范，通过职责分离、约定优于配置的理念，让开发者能够快速理解项目布局、定位文件、扩展功能。这套结构不仅支持单人快速开发，更适合多人团队协作，确保代码的可维护性和可扩展性。
理解TMaker的模板结构对于高效开发至关重要。从关键配置文件的职责划分，到页面、组件、样式的目录组织，再到规则系统的优先级机制，每个设计决策都有其深层原因。本文将系统介绍TMaker模板的目录结构、核心文件作用、页面与组件组织方式、配置规则优先级、以及实战中的最佳实践，帮助你构建结构清晰、易于维护的高质量模板项目。
概览
TMaker 的模板由页面、组件与配置组成，核心目标是让你以最小的学习成本完成高质量模板开发。整个系统采用约定优于配置的设计哲学，通过标准化的目录结构和命名规范，减少配置负担，提升开发效率。
核心设计理念
- 职责分离：页面、组件、样式、数据各司其职，边界清晰
- 约定优于配置：遵循标准目录结构，减少显式配置
- 渐进式复杂度：简单场景简单用，复杂场景有足够的扩展能力
- 工具友好：结构化设计便于IDE智能提示和AI辅助开发
- 团队协作：清晰的目录组织降低协作成本
技术栈
- 模板引擎：Scriban（类Liquid语法，功能强大）
- 样式系统：Tailwind CSS v4（@theme语法，原子化CSS）
- 数据格式：JSON（.data.json、.seo.json）
- 版本控制：Git友好，配置文件可追踪
- AI辅助：支持Claude Code、OpenAI Codex、GLM集成
目录结构详解
一个标准的TMaker模板项目包含以下目录和文件：
TMaker/
├── templates/ # 模板根目录
│ └── tmaker/ # 具体模板（tmaker是模板ID）
│ ├── template.json # 模板自定义配置
│ ├── template.spec.json # 模板规范定义（只读）
│ ├── package.json # 前端依赖和构建脚本
│ ├── pages/ # 页面目录
│ │ ├── index.sbn # 首页（Scriban模板）
│ │ ├── about.sbn # 关于页面
│ │ ├── blog/ # 博客模块
│ │ │ ├── index.sbn # 博客列表页
│ │ │ └── blogDetail/ # 博客详情页（TemplatePage）
│ │ │ ├── example.html # 文章正文
│ │ │ ├── example.data.json # 页面数据
│ │ │ └── example.seo.json # SEO元数据
│ │ └── docs/ # 文档模块
│ │ ├── index.sbn
│ │ └── docsDetail/ # 文档详情页
│ ├── components/ # 组件目录
│ │ ├── layout/ # 布局组件（全局注入）
│ │ │ ├── header.sbn # 页头
│ │ │ ├── footer.sbn # 页脚
│ │ │ └── navigation.sbn# 导航
│ │ ├── custom/ # 自定义组件（按需引入）
│ │ │ ├── ui/ # UI基础组件
│ │ │ │ ├── button.sbn
│ │ │ │ └── card.sbn
│ │ │ └── content/ # 内容组件
│ │ │ ├── article-card.sbn
│ │ │ └── author-bio.sbn
│ │ └── page/ # 页面模板组件
│ │ ├── docsDetail.sbn # 文档详情页模板
│ │ └── blogDetail.sbn # 博客详情页模板
│ ├── css/ # 样式目录
│ │ ├── site.css # 主样式文件（Tailwind v4）
│ │ └── components/ # 组件样式（可选）
│ ├── js/ # JavaScript目录
│ │ └── main.js # 主脚本
│ ├── images/ # 图片资源
│ │ ├── hero/ # Hero区域图片
│ │ ├── blog/ # 博客配图
│ │ └── icons/ # 图标
│ └── public/ # 静态资源（直接复制到输出）
│ ├── favicon.ico
│ └── robots.txt
├── templates_outputs/ # 渲染输出目录（不提交）
│ └── tmaker/ # 对应模板的输出
│ ├── index.html
│ ├── css/
│ ├── js/
│ └── images/
├── config.json # 本地配置（API密钥，不提交）
└── .gitignore # Git忽略规则
关键文件详解
1. template.json - 模板配置
这是模板的核心配置文件，定义了主题、色板、布局参数等自定义设置：
{
"name": "TMaker官方模板",
"version": "1.0.0",
"description": "现代化的模板开发框架",
"author": "TMaker Team",
"theme": {
"primaryColor": "#3b82f6",
"secondaryColor": "#8b5cf6",
"fontFamily": "Inter, sans-serif"
},
"layout": {
"containerWidth": "1280px",
"headerHeight": "64px",
"footerHeight": "240px"
},
"features": {
"darkMode": true,
"search": true,
"analytics": true
},
"injection": {
"headTop": "<link rel=\"preconnect\" href=\"https://fonts.googleapis.com\">",
"bodyBottom": "<script src=\"/js/main.js\"></script>"
}
}2. template.spec.json - 规范定义（只读）
系统级规范文件，定义了目录结构规则、命名约定、验证规则等。这个文件由TMaker系统维护，开发者不应手动修改：
{
"version": "1.0",
"directories": {
"pages": "pages/",
"components": "components/",
"css": "css/",
"images": "images/",
"public": "public/"
},
"rules": {
"cleanUrl": true,
"seoRequired": ["title", "description"],
"componentNaming": "kebab-case"
},
"validation": {
"requiredFiles": ["template.json", "package.json", "css/site.css"],
"pageExtensions": [".sbn", ".html"]
}
}3. css/site.css - 主样式文件
基于Tailwind CSS v4，使用@theme语法定义色板和设计令牌：
@import "tailwindcss";
@theme {
--color-primary: #3b82f6;
--color-secondary: #8b5cf6;
--color-accent: #f59e0b;
--font-sans: Inter, system-ui, sans-serif;
--font-mono: "JetBrains Mono", monospace;
--container-max-width: 1280px;
--spacing-section: 6rem;
}
/* 自定义组件样式 */
.btn-primary {
@apply bg-primary text-white px-6 py-3 rounded-lg hover:bg-primary/90;
}
4. config.json - 本地配置（敏感信息）
存储API密钥、认证令牌等敏感信息，必须添加到.gitignore：
{
"auth": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"email": "user@example.com"
},
"apiEndpoint": "https://api.aicms.com",
"preview": {
"port": 3000
}
}5. package.json - 前端依赖和构建
定义前端依赖、构建脚本和项目元数据：
{
"name": "tmaker-template",
"version": "1.0.0",
"scripts": {
"dev": "tailwindcss -i css/site.css -o public/css/site.css --watch",
"build": "tailwindcss -i css/site.css -o public/css/site.css --minify",
"preview": "tmaker preview tmaker"
},
"devDependencies": {
"tailwindcss": "^4.0.0"
}
}页面与组件组织
页面类型
TMaker支持两种页面类型，各有其适用场景：
- Scriban页面（.sbn）
- 适合结构化页面，如列表页、产品展示页
- 直接使用Scriban语法编写完整页面结构
- 数据通过
post.xxx访问 - 示例：
pages/blog/index.sbn（博客列表）
- TemplatePage（.html + .data.json + .seo.json）
- 适合内容为主的页面，如博客文章、文档
- .html包含纯HTML内容（不含html/head/body标签）
- .data.json包含标题、作者、日期等元数据
- .seo.json包含SEO优化信息
- 使用
components/page/下的共享模板渲染 - 示例：
pages/blog/blogDetail/my-article.html
组件三层架构
组件按职责分为三层，形成清晰的依赖关系：
components/
├── layout/ # 第1层：全局布局组件（自动注入）
│ ├── header.sbn - 站点页头，包含Logo和主导航
│ ├── footer.sbn - 站点页脚，包含版权和链接
│ └── navigation.sbn - 导航菜单组件
│
├── custom/ # 第2层：业务组件（按需引入）
│ ├── ui/ - 基础UI组件（按钮、卡片、模态框）
│ ├── content/ - 内容展示组件（文章卡片、作者信息）
│ ├── media/ - 媒体组件（图片、视频、图标）
│ └── interactive/ - 交互组件（表单、搜索、下拉菜单）
│
└── page/ # 第3层：页面模板组件（高级组合）
├── docsDetail.sbn - 文档详情页模板
└── blogDetail.sbn - 博客文章页模板
组件引入方式
<!-- 引入基础组件 -->
{{ include 'ui/button' }}
<!-- 传递参数 -->
{{ include 'ui/button' with {
text: '查看更多',
type: 'primary',
link: '/blog/'
} }}
<!-- 传递当前数据 -->
{{ include 'content/article-card' with post }}
<!-- 嵌套引入 -->
{{ include 'content/featured-section' }}
<!-- featured-section内部会引入其他组件 -->
规则优先级系统
TMaker采用三层规则优先级机制，上层规则覆盖下层规则。这套系统让项目既有统一规范，又保留定制灵活性。
优先级层次
- template.spec.json（最高优先级）
- 系统级规范，所有模板必须遵守
- 定义核心约束，如Clean URL、目录结构
- 不可被覆盖，确保平台一致性
- templates/code-rules.json（团队级规则）
- 团队共享的编码规范
- 可以扩展或细化系统规范
- 提交到版本库，团队成员共享
- template.json的code-rules.customRules（项目级规则）
- 单个模板的定制规则
- 最灵活，适应特殊需求
- 不应违反上层规范的核心约束
规则示例
// template.spec.json（系统级，不可修改）
{
"rules": {
"cleanUrl": true, // 所有链接必须以/结尾
"seoRequired": ["title", "description"],
"componentNaming": "kebab-case"
}
}
// templates/code-rules.json（团队级，可提交）
{
"customRules": {
"maxLineLength": 120,
"indentSize": 2,
"trailingComma": "always"
},
"linting": {
"enforceTypeChecking": true,
"requireDocstrings": ["components/custom"]
}
}
// template.json（项目级，最灵活）
{
"code-rules": {
"customRules": {
"allowInlineStyles": false,
"maxComponentDepth": 5
}
}
}
冲突解决
当多层规则有冲突时：
- 系统级规则不可被覆盖，违反会导致验证失败
- 团队级规则可被项目级规则覆盖
- 项目级规则只在当前模板生效
路由与URL映射
TMaker采用基于文件系统的路由，文件路径直接映射为URL路径。
路由规则
# Scriban页面
pages/index.sbn → /
pages/about.sbn → /about/
pages/blog/index.sbn → /blog/
pages/docs/getting-started.sbn → /docs/getting-started/
# TemplatePage（跳过分类目录）
pages/blog/blogDetail/my-article.html → /blog/my-article/
pages/docs/docsDetail/api-reference.html → /docs/api-reference/
# Clean URL要求
所有链接必须以 / 结尾
<a href="/blog/">博客</a> ✓ 正确
<a href="/blog">博客</a> ✗ 错误
<a href="/blog.html">博客</a> ✗ 错误
特殊路由
- 首页：
pages/index.sbn→/ - 404页面：
pages/404.sbn→ 所有未匹配路径 - 动态路由：通过数据文件和循环生成多个页面
最佳实践
1. 目录组织
- 按功能分组：将相关页面放在同一目录，如
pages/blog/、pages/docs/ - 组件细分：custom目录按功能领域细分子目录，避免扁平堆放
- 资源就近：图片等资源按模块组织，便于查找和管理
- 避免深层嵌套：目录层级不超过4层，保持结构简单
2. 命名规范
- 文件名：使用kebab-case（短横线），如
article-card.sbn - 组件名：与文件名对应，引入时直接使用
{{ include 'article-card' }} - 数据字段：使用camelCase（小驼峰），如
publishDate、authorName - CSS类名：遵循Tailwind原子化或BEM规范
3. 链接规范
- 所有页面链接必须包含
/后缀，如/docs/config/ - 使用绝对路径（从根目录开始），避免相对路径混乱
- 图片等资源路径以
/开头，如/images/hero.jpg - 外部链接添加
rel="noopener noreferrer"属性
4. 模板编写
.sbn文件只写body内容，不要包含<html>、<head>、<body>标签- 布局结构由系统和layout组件提供，页面专注内容
- 复杂页面拆分为多个小组件，保持单文件职责单一
- 组件内部使用
$0.xxx访问传递的参数
5. 数据组织
- 保持
.data.json结构扁平，避免深层嵌套 - 使用统一的字段命名，如所有日期都用
publishDate - 为可选字段提供默认值，避免undefined错误
- 大型数据考虑拆分为多个文件，按需加载
6. 版本控制
- 提交：模板文件、组件、配置文件（template.json、package.json）
- 忽略：
config.json、templates_outputs/、node_modules/、.tmaker/cache/ - 大型资源文件使用Git LFS或存储到CDN
- 提供
config.example.json作为配置模板
工具集成
VS Code推荐扩展
- Tailwind CSS IntelliSense：自动补全Tailwind类名
- Scriban Language：Scriban语法高亮和智能提示
- Prettier：代码格式化，保持风格一致
- ESLint：JavaScript代码检查
- JSON Language Features：JSON文件验证和格式化
AI辅助开发
推荐在VS Code中配合AI工具提升效率：
- Claude Code：擅长架构设计和代码重构，适合组件拆分
- OpenAI Codex：擅长生成Scriban模板和Tailwind样式
- GLM（智谱清言）：擅长中文内容生成和数据建模
项目迁移与升级
从旧版本升级
- 备份当前项目：
cp -r templates/tmaker templates/tmaker.backup - 升级 TMaker CLI 到新版本（根据官方发布方式更新）
- 检查模板结构与规则是否有变化，必要时手动调整
- 测试渲染：
tmaker render tmaker && tmaker preview tmaker
从其他平台迁移
从其他静态站点生成器迁移时，建议先整理页面与数据结构，再按 TMaker 规范手动落地到 templates/<id>。
常见问题排查
1. 目录结构不符合规范
问题：执行tmaker render提示目录结构错误
解决方案：
- 检查是否缺少必需目录（pages、components、css）
- 确认目录命名正确（区分大小写）
- 重新执行
tmaker render tmaker查看详细错误日志
2. 组件引入失败
问题：页面渲染时提示找不到组件
解决方案：
- 确认组件文件存在且路径正确
- 检查组件名拼写（区分大小写）
- 使用
{{ include 'button' }}（无需包含路径或扩展名）
3. 样式未生效
问题：页面显示但没有样式
解决方案：
- 确认执行了
npm install和npm run build - 检查
css/site.css是否存在且语法正确 - 验证输出目录是否包含构建后的CSS文件
总结
TMaker的模板结构设计充分体现了职责分离、约定优于配置、渐进式复杂度的理念。通过清晰的目录组织、三层组件架构、规则优先级系统，既保证了平台的统一规范，又提供了足够的定制灵活性。掌握模板结构的设计原理、关键文件的作用、页面与组件的组织方式，是高效使用TMaker的基础。
在实际开发中，遵循目录组织和命名规范，保持链接和数据格式的一致性，合理使用版本控制和工具集成，能够显著提升开发效率和代码质量。记住，良好的项目结构不是一次性设计出来的，而是在实践中持续优化和完善的结果。随着项目规模增长，定期审视和重构目录结构，保持代码整洁和可维护性，是长期成功的关键。
找不到你需要的内容？
联系我们