1. 项目概述一个被低估的静态站点生成利器如果你和我一样常年混迹在GitHub上热衷于寻找那些能提升开发效率、简化工作流的“小而美”工具那么你很可能已经对“静态站点生成器”这个概念感到审美疲劳了。从Jekyll、Hugo到Next.js、Gatsby选择多到让人眼花缭乱。但今天我想聊的这个项目——renatocaliari/starhtml-skill却让我眼前一亮。它没有动辄数千的Star文档看起来也朴实无华但恰恰是这种“返璞归真”的设计理念解决了我个人在构建小型项目文档、个人博客、甚至是内部工具展示页时的一大痛点如何在极致的轻量与足够的灵活性之间找到平衡点。这个项目本质上是一个基于Node.js的静态站点生成器SSG但它的核心哲学与主流方案截然不同。它不强制你学习一套新的模板语法如Jinja2、Go Templates也不要求你深度捆绑某个前端框架。它的核心技能Skill在于让你能够直接使用你早已熟悉的HTML、CSS和JavaScript来构建页面同时通过一种极其简洁的“星号HTML”StarHTML约定和Node.js脚本为这些静态文件注入动态数据与逻辑。你可以把它理解为一个“增强型HTML预处理器”或者一个“极简的SSG框架”。对于那些讨厌复杂构建步骤、只想快速将一些数据和模板变成可部署网站的全栈开发者、运维工程师或技术写作者来说这无疑是一股清流。我最初接触它是因为需要为一个内部API快速生成一份交互式文档。我不想引入庞大的VuePress或Docusaurus又觉得纯手写HTML维护起来太痛苦。starhtml-skill恰到好处地填补了这个空白。它允许我继续用普通的.html文件写页面结构用.css文件写样式然后用一个简单的JavaScript对象作为数据源通过几行Node.js脚本就能批量生成最终的静态页面。整个过程清晰、直接所有文件都在你的掌控之中没有黑盒魔法。2. 核心设计哲学与架构拆解2.1 为什么是“StarHTML”一种约定优于配置的模板思想项目名称中的“starhtml”是其灵魂所在。它并非一种新的文件格式而是一种在普通HTML文件中嵌入特殊标记的约定。这种标记以星号*开头用于标识那些需要在构建阶段被替换或处理的内容块。这种设计背后的逻辑非常务实零学习成本对于任何了解HTML的开发者和设计师几乎不需要学习新语法。你看到*title*就能直观地理解这里会被替换成标题。无侵入性这些星号标记在未经过处理的原始HTML文件中依然是有效的文本。你可以直接用浏览器打开这个文件进行样式和布局的调试星号标记不会破坏渲染只是显示为普通文本。这极大地提升了开发体验。关注点分离HTML文件只负责结构和“哪里需要填充数据”的标记而具体“填充什么数据”则由完全独立的JavaScript数据文件或脚本控制。这种分离比在HTML中写大量JavaScript模板字符串要清晰得多。举个例子一个典型的index.star.html源文件可能长这样!DOCTYPE html html langen head meta charsetUTF-8 title*pageTitle*/title link relstylesheet hrefstyles.css /head body header h1*siteName*/h1 nav ul *navigation* /ul /nav /header main article h2*postTitle*/h2 div classcontent *postContent* /div pPublished on: *postDate*/p /article /main footer p*footerText*/p /footer /body /html你可以看到所有动态部分都被*variableName*包围。这个文件本身是完整、可读的。2.2 “Skill”体现在何处极简的Node.js构建引擎项目的另一部分“skill”指的是其核心的Node.js处理脚本。它不是一个庞大的CLI工具而是一组你可以直接调用或稍作封装的函数。通常你需要自己编写一个简单的build.js脚本。这个脚本的核心工作流程清晰得惊人读取数据源从一个.js或.json文件中加载你的网站数据。这个数据可以是一个对象、一个数组或者任何JavaScript结构。遍历模板找到项目中的所有.star.html文件。模板替换对于每个模板文件读取其内容然后根据数据源查找并替换所有*variableName*标记。输出静态文件将替换后的内容写入到一个新的.html文件通常去掉.star后缀生成最终的、纯静态的网站。它的“技能”不在于功能繁多而在于精准地完成了从“模板数据”到“静态页面”的最短路径转换并且将控制权完全交还给开发者。你可以轻松地修改这个构建脚本添加你自己的处理逻辑比如压缩HTML、处理图片、或者生成Sitemap。2.3 与主流静态站点生成器的对比为了更清楚地定位starhtml-skill我们可以将其与几类常见工具做个对比特性starhtml-skillJekyll / HugoNext.js (静态导出)纯手写HTML学习曲线极低仅需HTMLJS基础中需学习特定模板语言Liquid/Go Templates高需熟悉React和Next.js生态低但扩展性差构建速度极快仅文本替换快但随内容量增长而变慢中等涉及Webpack打包无构建步骤灵活性高构建流程完全自定义中受限于引擎特性高但框架耦合性强低数据源任何JS可读取的格式JSON, JS对象主要支持Markdown、YAML等支持多种但配置复杂无适用场景小型项目页、简单博客、文档、原型标准博客、文档站复杂Web应用、SEO要求高的营销页单页、极少更新的页面部署复杂度极低仅需传输HTML/CSS/JS文件低但可能需要特定环境中需Node.js构建环境极低从这个对比可以看出starhtml-skill的核心优势在于简单场景下的超高效率和控制感。当你的项目不需要客户端路由、复杂的状态管理、或丰富的插件生态时它避免了“杀鸡用牛刀”的冗余复杂度。3. 从零开始实战构建一个个人项目展示页理论说得再多不如亲手实践。下面我将带你一步步使用starhtml-skill构建一个展示个人开源项目的静态页面。我们将创建一个包含项目列表、详细描述和标签过滤功能的页面。3.1 环境准备与项目初始化首先确保你的系统安装了Node.js建议版本12以上。然后创建一个新的项目目录并初始化。mkdir my-project-portfolio cd my-project-portfolio npm init -y接下来我们不需要从NPM安装starhtml-skill因为它本身不是一个库而是一个代码范例和思路。我们更推荐直接理解其思想并创建自己的构建脚本。不过我们可以创建一个简单的项目结构my-project-portfolio/ ├── build.js # 我们的核心构建脚本 ├── src/ # 源代码目录 │ ├── data.js # 网站数据 │ ├── templates/ # 模板文件 │ │ └── index.star.html │ └── assets/ # 静态资源CSS, JS, images │ ├── style.css │ └── main.js └── dist/ # 构建输出目录由脚本生成3.2 定义数据源用JavaScript对象管理内容在src/data.js中我们定义所有的页面内容。这种方式比JSON更灵活因为你可以包含函数、计算属性等。// src/data.js module.exports { siteMeta: { title: 我的开源项目集, description: 记录与分享我构建的一些小工具, author: 你的名字 }, projects: [ { id: 1, name: 任务管理CLI工具, description: 一个基于Node.js的命令行工具用于快速管理每日任务支持标签和优先级。, techStack: [Node.js, Commander.js, Lowdb], githubUrl: https://github.com/yourname/task-cli, featured: true }, { id: 2, name: 天气卡片组件, description: 一个轻量级、可定制的Vue组件用于展示当前天气信息。, techStack: [Vue.js, SCSS, Axios], githubUrl: https://github.com/yourname/weather-card, featured: true }, { id: 3, name: 本地文件搜索工具, description: 用于快速在指定目录下根据内容搜索文件的Python脚本。, techStack: [Python, Click], githubUrl: https://github.com/yourname/local-grep, featured: false } ], // 一个简单的函数用于生成所有不重复的技术标签 getAllTags() { const tags new Set(); this.projects.forEach(proj { proj.techStack.forEach(tag tags.add(tag)); }); return Array.from(tags); } };注意将数据保存在独立的.js文件中而不是直接内联在构建脚本里是一个好习惯。这使得内容维护和团队协作变得更容易非技术人员也可以在不接触代码的情况下修改内容需稍作指导。3.3 编写StarHTML模板保持HTML的纯粹现在创建我们的主模板src/templates/index.star.html。我们将设计一个包含项目列表和标签过滤器的页面。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title*siteMeta.title*/title meta namedescription content*siteMeta.description* link relstylesheet href/assets/style.css link relstylesheet hrefhttps://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css /head body header classsite-header div classcontainer h1*siteMeta.title*/h1 p classtagline*siteMeta.description*/p p classauthor由 *siteMeta.author* 维护/p /div /header main classcontainer section classfilters h2按技术栈筛选/h2 div classtags idtagContainer !-- 这里将被构建脚本动态替换为标签按钮 -- *renderTagFilters* /div button idclearFilters classbtn btn-secondary清除筛选/button /section section classproject-list h2项目列表 (*projects.length* 个)/h2 div classprojects-grid idprojectContainer !-- 这里将被构建脚本动态替换为项目卡片 -- *renderProjects* /div /section /main footer classsite-footer div classcontainer p最后更新于*buildTime*/p /div /footer script src/assets/main.js/script /body /html注意模板中的几个星号标记*siteMeta.title*等直接替换为简单变量。*projects.length*在构建时计算并替换。*renderTagFilters*和*renderProjects*这是关键。它们不是简单的变量而是需要调用渲染函数来生成一大段HTML字符串。这是我们实现灵活性的关键。3.4 核心构建脚本编写实现替换逻辑这是最核心的部分build.js。我们将实现文件读取、模板替换和静态文件生成。// build.js const fs require(fs).promises; const path require(path); // 1. 加载数据 const data require(./src/data.js); // 2. 辅助渲染函数 function renderProjects(projects) { // 这个函数在构建时运行生成静态的HTML字符串 return projects.map(proj div classproject-card>/* 基础样式 */ .container { max-width: 1200px; margin: 0 auto; padding: 0 20px; } .project-list { margin-top: 3rem; } /* 项目网格 */ .projects-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: 2rem; margin-top: 1.5rem; } /* 项目卡片 */ .project-card { border: 1px solid #e1e4e8; border-radius: 8px; padding: 1.5rem; background: #fff; transition: transform 0.2s, box-shadow 0.2s; } .project-card:hover { transform: translateY(-4px); box-shadow: 0 6px 12px rgba(0,0,0,0.1); } /* 技术标签 */ .tech-tags { margin: 1rem 0; } .tech-tag { display: inline-block; background: #f1f8ff; color: #0366d6; padding: 0.2rem 0.6rem; border-radius: 12px; font-size: 0.85rem; margin-right: 0.5rem; margin-bottom: 0.5rem; } /* 筛选器标签按钮 */ .tags { margin: 1rem 0; } .tag-filter { padding: 0.5rem 1rem; margin: 0.3rem; border: 1px solid #ddd; background: #f9f9f9; border-radius: 4px; cursor: pointer; } .tag-filter.active { background: #0366d6; color: white; border-color: #0366d6; }src/assets/main.js(前端过滤逻辑)// 前端筛选功能 document.addEventListener(DOMContentLoaded, function() { const projectCards document.querySelectorAll(.project-card); const tagButtons document.querySelectorAll(.tag-filter); const clearButton document.getElementById(clearFilters); let activeTags new Set(); // 标签按钮点击事件 tagButtons.forEach(button { button.addEventListener(click, function() { const tag this.dataset.tag; this.classList.toggle(active); if (activeTags.has(tag)) { activeTags.delete(tag); } else { activeTags.add(tag); } filterProjects(); }); }); // 清除筛选 clearButton.addEventListener(click, function() { activeTags.clear(); tagButtons.forEach(btn btn.classList.remove(active)); filterProjects(); }); // 筛选项目函数 function filterProjects() { projectCards.forEach(card { const cardTags card.dataset.tags.split(,).map(t t.trim()); let shouldShow true; if (activeTags.size 0) { // 检查卡片是否包含所有激活的标签AND逻辑 shouldShow Array.from(activeTags).every(tag cardTags.includes(tag)); } card.style.display shouldShow ? block : none; }); } });3.6 运行构建与查看结果在项目根目录下运行构建脚本node build.js如果一切顺利你将在dist目录下看到生成的index.html以及复制过来的assets文件夹。直接用浏览器打开dist/index.html你就能看到一个功能完整的项目展示页。页面上的项目卡片和标签按钮都是静态HTML但通过我们构建时注入的>!DOCTYPE html html head meta charsetUTF-8 title*title* | *siteMeta.title*/title link relstylesheet href/assets/style.css /head body header.../header main *content* !-- 内容注入点 -- /main footer.../footer /body /html创建内容模板src/templates/about.star.html*extends:layout* *block:title*关于我*endblock* *block:content* h1关于我/h1 p这里是关于我的介绍.../p *endblock*这里我们模拟了一个简单的模板继承语法。在构建脚本中我们需要解析*extends:*和*block:*指令。升级构建脚本修改build.js添加解析布局和块的功能。这需要更复杂的字符串解析但核心逻辑依然是查找和替换。你可以先读取布局模板然后找到内容模板中的块定义用块内容替换布局模板中对应的*block:blockName*位置。注意事项自己实现一套完整的模板继承引擎可能会变得复杂。如果项目需要非常复杂的多页面和布局这可能意味着starhtml-skill的极简哲学已不适用可以考虑迁移到更成熟的SSG。但对于5-10个页面的小型网站这种手动或半自动的布局管理是完全可控的。4.2 集成Markdown渲染很多技术内容习惯用Markdown书写。我们可以轻松集成一个Markdown解析器如marked在构建过程中将.md文件转换为HTML字符串然后注入到StarHTML模板中。安装markednpm install marked在build.js中引入并配置const marked require(marked); // 在构建循环中 if (file.endsWith(.star.md)) { const mdContent await fs.readFile(path.join(templateDir, file), utf-8); const htmlContent marked.parse(mdContent); // 然后将 htmlContent 作为变量嵌入到主HTML模板中 // 例如主模板中有一个 *markdownContent* 标记 }这样你就可以用Markdown写博客文章然后用统一的页面模板来展示它们。4.3 自动化与部署优化为了让开发流程更顺畅可以考虑以下优化开发服务器写一个简单的server.js使用http或express模块监听文件变化使用chokidar库自动重新构建并刷新浏览器通过LiveReload或BrowserSync。这能获得接近现代前端框架的热更新体验。构建优化在build.js的最后阶段可以集成html-minifier压缩HTML用clean-css压缩CSS用terser压缩JS甚至用sharp处理并优化图片。部署由于输出是纯静态文件你可以直接部署到任何静态托管服务如 GitHub Pages, Netlify, Vercel, 或你自己的Nginx服务器。在Netlify或Vercel上你只需要将构建命令设置为node build.js发布目录设置为dist即可。5. 常见问题与排查技巧实录在实际使用中你可能会遇到一些典型问题。以下是我踩过的一些坑和解决方案。5.1 变量未替换或替换错误这是最常见的问题。症状生成的HTML中仍然残留着*variableName*星号标记。排查检查变量名拼写确保模板中的标记名与数据对象中的属性名完全一致包括大小写。*siteTitle*和*sitetitle*是不同的。检查替换逻辑在build.js的替换环节后添加一个console.log(content)查看替换后的内容片段确认替换是否发生。正则表达式陷阱如果你使用正则表达式进行全局替换如/\\*title\\*/g要小心特殊字符。对于复杂的、可能包含换行符的块替换建议使用字符串的replace方法进行精确匹配或者使用更稳健的模板函数。避坑技巧为替换函数增加严格的调试日志。例如在替换每个变量前打印一条日志console.log(Replacing marker: ${marker} with: ${data[prop]})。这能帮你快速定位是哪个变量出了问题。5.2 构建脚本性能随文件增多而下降症状当模板或数据文件非常多时构建速度明显变慢。优化方案异步并行处理使用Promise.all()来并行处理多个模板文件的读取和写入而不是用for...of循环。const buildPromises starHtmlFiles.map(async (file) { // ... 处理单个文件的逻辑 }); await Promise.all(buildPromises);增量构建高级记录文件的哈希值只重新构建发生变化的模板或数据文件。这需要更复杂的脚本逻辑但对于大型项目很有必要。避免重复读取数据确保数据源如data.js只被加载一次并在整个构建过程中复用。5.3 如何处理嵌套数据或循环中的复杂逻辑问题数据中可能包含数组的数组或者需要在循环内进行条件判断。解决方案将复杂的渲染逻辑完全封装在构建脚本的渲染函数中。不要在模板里写逻辑判断因为模板只是文本。例如如果项目有一个relatedProjects的数组属性就在renderProjects函数内部处理它的渲染。function renderProjectDetail(project) { let html h2${project.name}/h2; html p${project.description}/p; if (project.relatedProjects project.relatedProjects.length 0) { html h3相关项目/h3ul; project.relatedProjects.forEach(rel { html lia href#${rel.id}${rel.name}/a/li; }); html /ul; } return html; }然后在模板中只需一个标记*projectDetail*。这样保持了模板的简洁也将所有逻辑集中在可控的JavaScript中。5.4 生成的HTML结构混乱或格式错误症状生成的HTML标签不闭合或缩进混乱难以调试。预防与解决在渲染函数中返回格式良好的HTML字符串虽然不影响浏览器渲染但良好的缩进对开发者调试友好。可以使用模板字符串的多行特性并注意缩进。使用HTML格式化工具在构建脚本的最后引入一个像js-beautify这样的库对生成的HTML文件进行格式化。严格检查模板确保你的.star.html源文件本身是格式良好、标签闭合的HTML。可以在构建前用HTML验证器检查一下。5.5 如何管理多个环境开发/生产需求开发时可能需要打印调试信息而生产环境需要压缩资源。实现通过Node.js的环境变量process.env.NODE_ENV来区分。// build.js const isProduction process.env.NODE_ENV production; async function build() { // ... 其他逻辑 if (isProduction) { // 执行压缩、混淆等优化操作 content minifyHtml(content); } else { // 添加开发注释或源码映射 content !-- Built at ${new Date().toISOString()} --\n content; } }运行构建时使用NODE_ENVproduction node build.js。回顾整个实践过程starhtml-skill带给我的最大启示是工具的价值不在于它有多强大而在于它是否恰到好处地解决了你的问题。对于大量需要快速搭建、内容驱动、且希望保持技术栈简单明了的小型项目自己动手基于这种“增强型HTML”的思想打造一套构建流程其带来的掌控感和灵活性远比勉强使用一个庞大框架要舒服得多。它让你重新关注内容本身而不是工具的配置。当你下次需要一个简单的展示页、活动页或文档时不妨试试这个思路或许会有意想不到的轻松体验。
StarHTML：极简静态站点生成方案，用HTML+JS实现轻量级SSG
发布时间：2026/5/17 5:43:39
1. 项目概述一个被低估的静态站点生成利器如果你和我一样常年混迹在GitHub上热衷于寻找那些能提升开发效率、简化工作流的“小而美”工具那么你很可能已经对“静态站点生成器”这个概念感到审美疲劳了。从Jekyll、Hugo到Next.js、Gatsby选择多到让人眼花缭乱。但今天我想聊的这个项目——renatocaliari/starhtml-skill却让我眼前一亮。它没有动辄数千的Star文档看起来也朴实无华但恰恰是这种“返璞归真”的设计理念解决了我个人在构建小型项目文档、个人博客、甚至是内部工具展示页时的一大痛点如何在极致的轻量与足够的灵活性之间找到平衡点。这个项目本质上是一个基于Node.js的静态站点生成器SSG但它的核心哲学与主流方案截然不同。它不强制你学习一套新的模板语法如Jinja2、Go Templates也不要求你深度捆绑某个前端框架。它的核心技能Skill在于让你能够直接使用你早已熟悉的HTML、CSS和JavaScript来构建页面同时通过一种极其简洁的“星号HTML”StarHTML约定和Node.js脚本为这些静态文件注入动态数据与逻辑。你可以把它理解为一个“增强型HTML预处理器”或者一个“极简的SSG框架”。对于那些讨厌复杂构建步骤、只想快速将一些数据和模板变成可部署网站的全栈开发者、运维工程师或技术写作者来说这无疑是一股清流。我最初接触它是因为需要为一个内部API快速生成一份交互式文档。我不想引入庞大的VuePress或Docusaurus又觉得纯手写HTML维护起来太痛苦。starhtml-skill恰到好处地填补了这个空白。它允许我继续用普通的.html文件写页面结构用.css文件写样式然后用一个简单的JavaScript对象作为数据源通过几行Node.js脚本就能批量生成最终的静态页面。整个过程清晰、直接所有文件都在你的掌控之中没有黑盒魔法。2. 核心设计哲学与架构拆解2.1 为什么是“StarHTML”一种约定优于配置的模板思想项目名称中的“starhtml”是其灵魂所在。它并非一种新的文件格式而是一种在普通HTML文件中嵌入特殊标记的约定。这种标记以星号*开头用于标识那些需要在构建阶段被替换或处理的内容块。这种设计背后的逻辑非常务实零学习成本对于任何了解HTML的开发者和设计师几乎不需要学习新语法。你看到*title*就能直观地理解这里会被替换成标题。无侵入性这些星号标记在未经过处理的原始HTML文件中依然是有效的文本。你可以直接用浏览器打开这个文件进行样式和布局的调试星号标记不会破坏渲染只是显示为普通文本。这极大地提升了开发体验。关注点分离HTML文件只负责结构和“哪里需要填充数据”的标记而具体“填充什么数据”则由完全独立的JavaScript数据文件或脚本控制。这种分离比在HTML中写大量JavaScript模板字符串要清晰得多。举个例子一个典型的index.star.html源文件可能长这样!DOCTYPE html html langen head meta charsetUTF-8 title*pageTitle*/title link relstylesheet hrefstyles.css /head body header h1*siteName*/h1 nav ul *navigation* /ul /nav /header main article h2*postTitle*/h2 div classcontent *postContent* /div pPublished on: *postDate*/p /article /main footer p*footerText*/p /footer /body /html你可以看到所有动态部分都被*variableName*包围。这个文件本身是完整、可读的。2.2 “Skill”体现在何处极简的Node.js构建引擎项目的另一部分“skill”指的是其核心的Node.js处理脚本。它不是一个庞大的CLI工具而是一组你可以直接调用或稍作封装的函数。通常你需要自己编写一个简单的build.js脚本。这个脚本的核心工作流程清晰得惊人读取数据源从一个.js或.json文件中加载你的网站数据。这个数据可以是一个对象、一个数组或者任何JavaScript结构。遍历模板找到项目中的所有.star.html文件。模板替换对于每个模板文件读取其内容然后根据数据源查找并替换所有*variableName*标记。输出静态文件将替换后的内容写入到一个新的.html文件通常去掉.star后缀生成最终的、纯静态的网站。它的“技能”不在于功能繁多而在于精准地完成了从“模板数据”到“静态页面”的最短路径转换并且将控制权完全交还给开发者。你可以轻松地修改这个构建脚本添加你自己的处理逻辑比如压缩HTML、处理图片、或者生成Sitemap。2.3 与主流静态站点生成器的对比为了更清楚地定位starhtml-skill我们可以将其与几类常见工具做个对比特性starhtml-skillJekyll / HugoNext.js (静态导出)纯手写HTML学习曲线极低仅需HTMLJS基础中需学习特定模板语言Liquid/Go Templates高需熟悉React和Next.js生态低但扩展性差构建速度极快仅文本替换快但随内容量增长而变慢中等涉及Webpack打包无构建步骤灵活性高构建流程完全自定义中受限于引擎特性高但框架耦合性强低数据源任何JS可读取的格式JSON, JS对象主要支持Markdown、YAML等支持多种但配置复杂无适用场景小型项目页、简单博客、文档、原型标准博客、文档站复杂Web应用、SEO要求高的营销页单页、极少更新的页面部署复杂度极低仅需传输HTML/CSS/JS文件低但可能需要特定环境中需Node.js构建环境极低从这个对比可以看出starhtml-skill的核心优势在于简单场景下的超高效率和控制感。当你的项目不需要客户端路由、复杂的状态管理、或丰富的插件生态时它避免了“杀鸡用牛刀”的冗余复杂度。3. 从零开始实战构建一个个人项目展示页理论说得再多不如亲手实践。下面我将带你一步步使用starhtml-skill构建一个展示个人开源项目的静态页面。我们将创建一个包含项目列表、详细描述和标签过滤功能的页面。3.1 环境准备与项目初始化首先确保你的系统安装了Node.js建议版本12以上。然后创建一个新的项目目录并初始化。mkdir my-project-portfolio cd my-project-portfolio npm init -y接下来我们不需要从NPM安装starhtml-skill因为它本身不是一个库而是一个代码范例和思路。我们更推荐直接理解其思想并创建自己的构建脚本。不过我们可以创建一个简单的项目结构my-project-portfolio/ ├── build.js # 我们的核心构建脚本 ├── src/ # 源代码目录 │ ├── data.js # 网站数据 │ ├── templates/ # 模板文件 │ │ └── index.star.html │ └── assets/ # 静态资源CSS, JS, images │ ├── style.css │ └── main.js └── dist/ # 构建输出目录由脚本生成3.2 定义数据源用JavaScript对象管理内容在src/data.js中我们定义所有的页面内容。这种方式比JSON更灵活因为你可以包含函数、计算属性等。// src/data.js module.exports { siteMeta: { title: 我的开源项目集, description: 记录与分享我构建的一些小工具, author: 你的名字 }, projects: [ { id: 1, name: 任务管理CLI工具, description: 一个基于Node.js的命令行工具用于快速管理每日任务支持标签和优先级。, techStack: [Node.js, Commander.js, Lowdb], githubUrl: https://github.com/yourname/task-cli, featured: true }, { id: 2, name: 天气卡片组件, description: 一个轻量级、可定制的Vue组件用于展示当前天气信息。, techStack: [Vue.js, SCSS, Axios], githubUrl: https://github.com/yourname/weather-card, featured: true }, { id: 3, name: 本地文件搜索工具, description: 用于快速在指定目录下根据内容搜索文件的Python脚本。, techStack: [Python, Click], githubUrl: https://github.com/yourname/local-grep, featured: false } ], // 一个简单的函数用于生成所有不重复的技术标签 getAllTags() { const tags new Set(); this.projects.forEach(proj { proj.techStack.forEach(tag tags.add(tag)); }); return Array.from(tags); } };注意将数据保存在独立的.js文件中而不是直接内联在构建脚本里是一个好习惯。这使得内容维护和团队协作变得更容易非技术人员也可以在不接触代码的情况下修改内容需稍作指导。3.3 编写StarHTML模板保持HTML的纯粹现在创建我们的主模板src/templates/index.star.html。我们将设计一个包含项目列表和标签过滤器的页面。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title*siteMeta.title*/title meta namedescription content*siteMeta.description* link relstylesheet href/assets/style.css link relstylesheet hrefhttps://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css /head body header classsite-header div classcontainer h1*siteMeta.title*/h1 p classtagline*siteMeta.description*/p p classauthor由 *siteMeta.author* 维护/p /div /header main classcontainer section classfilters h2按技术栈筛选/h2 div classtags idtagContainer !-- 这里将被构建脚本动态替换为标签按钮 -- *renderTagFilters* /div button idclearFilters classbtn btn-secondary清除筛选/button /section section classproject-list h2项目列表 (*projects.length* 个)/h2 div classprojects-grid idprojectContainer !-- 这里将被构建脚本动态替换为项目卡片 -- *renderProjects* /div /section /main footer classsite-footer div classcontainer p最后更新于*buildTime*/p /div /footer script src/assets/main.js/script /body /html注意模板中的几个星号标记*siteMeta.title*等直接替换为简单变量。*projects.length*在构建时计算并替换。*renderTagFilters*和*renderProjects*这是关键。它们不是简单的变量而是需要调用渲染函数来生成一大段HTML字符串。这是我们实现灵活性的关键。3.4 核心构建脚本编写实现替换逻辑这是最核心的部分build.js。我们将实现文件读取、模板替换和静态文件生成。// build.js const fs require(fs).promises; const path require(path); // 1. 加载数据 const data require(./src/data.js); // 2. 辅助渲染函数 function renderProjects(projects) { // 这个函数在构建时运行生成静态的HTML字符串 return projects.map(proj div classproject-card>/* 基础样式 */ .container { max-width: 1200px; margin: 0 auto; padding: 0 20px; } .project-list { margin-top: 3rem; } /* 项目网格 */ .projects-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: 2rem; margin-top: 1.5rem; } /* 项目卡片 */ .project-card { border: 1px solid #e1e4e8; border-radius: 8px; padding: 1.5rem; background: #fff; transition: transform 0.2s, box-shadow 0.2s; } .project-card:hover { transform: translateY(-4px); box-shadow: 0 6px 12px rgba(0,0,0,0.1); } /* 技术标签 */ .tech-tags { margin: 1rem 0; } .tech-tag { display: inline-block; background: #f1f8ff; color: #0366d6; padding: 0.2rem 0.6rem; border-radius: 12px; font-size: 0.85rem; margin-right: 0.5rem; margin-bottom: 0.5rem; } /* 筛选器标签按钮 */ .tags { margin: 1rem 0; } .tag-filter { padding: 0.5rem 1rem; margin: 0.3rem; border: 1px solid #ddd; background: #f9f9f9; border-radius: 4px; cursor: pointer; } .tag-filter.active { background: #0366d6; color: white; border-color: #0366d6; }src/assets/main.js(前端过滤逻辑)// 前端筛选功能 document.addEventListener(DOMContentLoaded, function() { const projectCards document.querySelectorAll(.project-card); const tagButtons document.querySelectorAll(.tag-filter); const clearButton document.getElementById(clearFilters); let activeTags new Set(); // 标签按钮点击事件 tagButtons.forEach(button { button.addEventListener(click, function() { const tag this.dataset.tag; this.classList.toggle(active); if (activeTags.has(tag)) { activeTags.delete(tag); } else { activeTags.add(tag); } filterProjects(); }); }); // 清除筛选 clearButton.addEventListener(click, function() { activeTags.clear(); tagButtons.forEach(btn btn.classList.remove(active)); filterProjects(); }); // 筛选项目函数 function filterProjects() { projectCards.forEach(card { const cardTags card.dataset.tags.split(,).map(t t.trim()); let shouldShow true; if (activeTags.size 0) { // 检查卡片是否包含所有激活的标签AND逻辑 shouldShow Array.from(activeTags).every(tag cardTags.includes(tag)); } card.style.display shouldShow ? block : none; }); } });3.6 运行构建与查看结果在项目根目录下运行构建脚本node build.js如果一切顺利你将在dist目录下看到生成的index.html以及复制过来的assets文件夹。直接用浏览器打开dist/index.html你就能看到一个功能完整的项目展示页。页面上的项目卡片和标签按钮都是静态HTML但通过我们构建时注入的>!DOCTYPE html html head meta charsetUTF-8 title*title* | *siteMeta.title*/title link relstylesheet href/assets/style.css /head body header.../header main *content* !-- 内容注入点 -- /main footer.../footer /body /html创建内容模板src/templates/about.star.html*extends:layout* *block:title*关于我*endblock* *block:content* h1关于我/h1 p这里是关于我的介绍.../p *endblock*这里我们模拟了一个简单的模板继承语法。在构建脚本中我们需要解析*extends:*和*block:*指令。升级构建脚本修改build.js添加解析布局和块的功能。这需要更复杂的字符串解析但核心逻辑依然是查找和替换。你可以先读取布局模板然后找到内容模板中的块定义用块内容替换布局模板中对应的*block:blockName*位置。注意事项自己实现一套完整的模板继承引擎可能会变得复杂。如果项目需要非常复杂的多页面和布局这可能意味着starhtml-skill的极简哲学已不适用可以考虑迁移到更成熟的SSG。但对于5-10个页面的小型网站这种手动或半自动的布局管理是完全可控的。4.2 集成Markdown渲染很多技术内容习惯用Markdown书写。我们可以轻松集成一个Markdown解析器如marked在构建过程中将.md文件转换为HTML字符串然后注入到StarHTML模板中。安装markednpm install marked在build.js中引入并配置const marked require(marked); // 在构建循环中 if (file.endsWith(.star.md)) { const mdContent await fs.readFile(path.join(templateDir, file), utf-8); const htmlContent marked.parse(mdContent); // 然后将 htmlContent 作为变量嵌入到主HTML模板中 // 例如主模板中有一个 *markdownContent* 标记 }这样你就可以用Markdown写博客文章然后用统一的页面模板来展示它们。4.3 自动化与部署优化为了让开发流程更顺畅可以考虑以下优化开发服务器写一个简单的server.js使用http或express模块监听文件变化使用chokidar库自动重新构建并刷新浏览器通过LiveReload或BrowserSync。这能获得接近现代前端框架的热更新体验。构建优化在build.js的最后阶段可以集成html-minifier压缩HTML用clean-css压缩CSS用terser压缩JS甚至用sharp处理并优化图片。部署由于输出是纯静态文件你可以直接部署到任何静态托管服务如 GitHub Pages, Netlify, Vercel, 或你自己的Nginx服务器。在Netlify或Vercel上你只需要将构建命令设置为node build.js发布目录设置为dist即可。5. 常见问题与排查技巧实录在实际使用中你可能会遇到一些典型问题。以下是我踩过的一些坑和解决方案。5.1 变量未替换或替换错误这是最常见的问题。症状生成的HTML中仍然残留着*variableName*星号标记。排查检查变量名拼写确保模板中的标记名与数据对象中的属性名完全一致包括大小写。*siteTitle*和*sitetitle*是不同的。检查替换逻辑在build.js的替换环节后添加一个console.log(content)查看替换后的内容片段确认替换是否发生。正则表达式陷阱如果你使用正则表达式进行全局替换如/\\*title\\*/g要小心特殊字符。对于复杂的、可能包含换行符的块替换建议使用字符串的replace方法进行精确匹配或者使用更稳健的模板函数。避坑技巧为替换函数增加严格的调试日志。例如在替换每个变量前打印一条日志console.log(Replacing marker: ${marker} with: ${data[prop]})。这能帮你快速定位是哪个变量出了问题。5.2 构建脚本性能随文件增多而下降症状当模板或数据文件非常多时构建速度明显变慢。优化方案异步并行处理使用Promise.all()来并行处理多个模板文件的读取和写入而不是用for...of循环。const buildPromises starHtmlFiles.map(async (file) { // ... 处理单个文件的逻辑 }); await Promise.all(buildPromises);增量构建高级记录文件的哈希值只重新构建发生变化的模板或数据文件。这需要更复杂的脚本逻辑但对于大型项目很有必要。避免重复读取数据确保数据源如data.js只被加载一次并在整个构建过程中复用。5.3 如何处理嵌套数据或循环中的复杂逻辑问题数据中可能包含数组的数组或者需要在循环内进行条件判断。解决方案将复杂的渲染逻辑完全封装在构建脚本的渲染函数中。不要在模板里写逻辑判断因为模板只是文本。例如如果项目有一个relatedProjects的数组属性就在renderProjects函数内部处理它的渲染。function renderProjectDetail(project) { let html h2${project.name}/h2; html p${project.description}/p; if (project.relatedProjects project.relatedProjects.length 0) { html h3相关项目/h3ul; project.relatedProjects.forEach(rel { html lia href#${rel.id}${rel.name}/a/li; }); html /ul; } return html; }然后在模板中只需一个标记*projectDetail*。这样保持了模板的简洁也将所有逻辑集中在可控的JavaScript中。5.4 生成的HTML结构混乱或格式错误症状生成的HTML标签不闭合或缩进混乱难以调试。预防与解决在渲染函数中返回格式良好的HTML字符串虽然不影响浏览器渲染但良好的缩进对开发者调试友好。可以使用模板字符串的多行特性并注意缩进。使用HTML格式化工具在构建脚本的最后引入一个像js-beautify这样的库对生成的HTML文件进行格式化。严格检查模板确保你的.star.html源文件本身是格式良好、标签闭合的HTML。可以在构建前用HTML验证器检查一下。5.5 如何管理多个环境开发/生产需求开发时可能需要打印调试信息而生产环境需要压缩资源。实现通过Node.js的环境变量process.env.NODE_ENV来区分。// build.js const isProduction process.env.NODE_ENV production; async function build() { // ... 其他逻辑 if (isProduction) { // 执行压缩、混淆等优化操作 content minifyHtml(content); } else { // 添加开发注释或源码映射 content !-- Built at ${new Date().toISOString()} --\n content; } }运行构建时使用NODE_ENVproduction node build.js。回顾整个实践过程starhtml-skill带给我的最大启示是工具的价值不在于它有多强大而在于它是否恰到好处地解决了你的问题。对于大量需要快速搭建、内容驱动、且希望保持技术栈简单明了的小型项目自己动手基于这种“增强型HTML”的思想打造一套构建流程其带来的掌控感和灵活性远比勉强使用一个庞大框架要舒服得多。它让你重新关注内容本身而不是工具的配置。当你下次需要一个简单的展示页、活动页或文档时不妨试试这个思路或许会有意想不到的轻松体验。
