1. 为什么你需要一个 caveman 占位页caveman 这个词直译是穴居人。我第一次跑完npx caveman的时候觉得这个命名太传神了——它干的事情确实是给你一个最原始、最不修边幅但立刻能用的占位页面。做网站开发的人应该都有过这种经历产品要 demo 地址客户催着看效果域名已经解析了可业务页面还在画原型或者活动页排期跟不上主站又不能裸奔总得有个体面的东西顶着。这个时候一个不会出错、不依赖后端、几秒钟就能生成的静态页就是救火队员。caveman 这类工具解决的正是在正式页面还没完成的空档期里给访客一个稳定、友好、可解释的过渡页面。它做的是施工中 / 即将上线 / 404 兜底这类场景产出一个纯净的静态 HTML 文件不引入构建链不强制你用 React、Vue 或者任何运行时框架。独立开发者拿它顶项目间隙前端工程师拿它做分支预览黑客松选手拿它当门面都很合适。你不需要会任何框架只需要一条命令。1.1 三个最典型的应用场景我实际用下来占位页的需求无外乎下面几类你可以对照自己的情况判断适用性。第一个场景是项目已经立项但 Demo 日期已定。这种情况在 To B 项目里特别常见商务合同签了客户就要看到一个能点的网页哪怕里面全是假数据。与其熬夜赶一个半成品业务页不如先放一个设计感尚可的占位页写明产品名称、上线时间、联系邮箱把预期管理做好。访客不会觉得你项目黄了只会认为还没到时间。第二个场景是域名买了服务器 / 备案还没就绪。域名解析是秒级的但服务器部署、ICP 备案这类流程通常是按天算的。这时候你没法让访问者看到连接被拒绝或者 Nginx 的默认欢迎页——那看起来太像网站没人管了。丢一个占位页上去访客至少知道这里将来有个东西。第三个场景是主站在维护或者活动页出了事故。线上服务要临时维护或者页面被误删、接口挂了你可以把流量导到一个静态 503 / 维护页面上。静态页不会因为后端故障跟着一起挂这一点在故障时刻特别关键。1.2 和手写页面 / 脚手架方案的对比可能有人说一个占位页而已我手写不就行了确实行但我见过太多手写页面翻车的案例——样式表没引对、字体跨域加载失败、移动端一塌糊涂本来只想花五分钟结果调了一个小时。而脚手架方案又属于杀鸡用牛刀为了一个coming soon页面初始化一个 Vite 工程装十八个依赖构建产物一堆 chunk 文件维护成本和页面本身的价值完全不成正比。放一张对比表你自己感受一下方案耗时依赖部署复杂程度可维护性手写 HTML10 分钟起且容易漏样式无低但质量看运气改起来要重新编辑前端脚手架30 分钟以上构建链高需持续维护依赖页面太重付费落地页 SaaS注册 配置第三方账号中受限于平台模板不一定可控caveman 这类工具一分钟以内npm可选极低单文件拷贝模板可沉淀复用这里不是说手写页一无是处只是它把注意力和时间浪费在了本来就不该花时间的地方。占位页是个过渡产物它最重要的属性是快、稳定、不添乱。caveman 的价值就是把这三件事打包成一个命令。1.3 为什么是纯静态单文件而不是别的占位页这个场景有一个天然约束它不能依赖服务器端渲染更不能依赖数据库。理由很简单你在等服务器就绪的时候服务器本身可能是不可用的你在等后端接口的时候接口也大概率是空的。如果占位页还要走一遍后端链路那它和正式页就没什么区别了故障时照样抓瞎。纯静态单文件的好处在于它可以被扔到任何地方——对象存储、CDN、GitHub Pages、Netlify随便一个静态托管都能运行而且永远不会因为业务系统崩溃而不可访问。另一个容易被忽略的点是单文件这个属性。它意味着你可以把它直接塞进一个 Git 仓库的根目录或docs文件夹不需要配置构建命令不需要管资源路径更不会出现部署后 CSS 找不到、图片全裂的情况。我之前接过一个项目团队把占位页做成了一个 Vue 单页应用那个页面本身确实好看但每次部署都要跑一遍npm install、npm run build几个月后依赖出问题连施工中三个字都显示不出来。这就是典型的方案过重带来的反噬。2. 核心细节解析与实操要点从 npx 到参考模板说清楚了定位接下来进入实操。caveman 这类工具通常有两种使用姿势一种是直接用npx一种是装进项目的devDependencies里跑。我两种都用过各自有适用场景。2.1 安装与初始化npx、全局安装还是本地依赖先讲最常规的姿势一行命令npx cavemannpx是 npm 自带的工具执行器它的设计初衷就是解决临时用一下某个命令行工具的问题。它会先在本地的node_modules/.bin里找有没有这个命令找不到就去 npm 仓库拉最新版到缓存里执行用完即走不会污染全局环境变量。这一点对占位页工具特别合适因为你不是天天都在生成占位页没必要全局装一个常驻命令。如果你的使用频率很高——比如你是团队的脚手架负责人或者经常需要批量生成演示项目——可以考虑全局安装一次npm install -g caveman全局安装的代价是后续升级要靠自己关注而且在不同机器上容易版本不一致我个人还是建议优先用npx。还有一种进阶用法是把 caveman 装进项目的开发依赖在package.json里专门留一个脚本{ scripts: { preview:placeholder: caveman --output preview --title Preview Site } }这样做的目的是让占位页的生成逻辑跟着仓库走团队协作时任何人拉下来代码都能用同一条命令生成相同的占位页不会出现我机器上能跑你那边不行的问题。2.2 配置项怎么填标题、副标题、主题色和联系方式多数占位页工具都提供命令行参数或者一个配置文件以便你能在不修改模板的情况下快速改掉页面上的核心信息。不同版本的caveman支持的参数可能有差异所以第一件事永远是看帮助文档npx caveman --help以这类工具的通用配置习惯来说你大概率会用到这几种配置配置项作用示例title页面主标题通常显示在页面的正中央Acme Inc.subtitle辅助说明文案告诉访客这里正在发生什么我们正在全力搭建稍后回来accent强调色 / 主题色决定页面的整体色调#4F46E5email联系邮箱让访客有渠道联系到团队helloexample.commode页面模式常见有 coming-soon / 404 / maintenancecoming-soonoutput输出目录决定产物写到哪里dist配置文件的格式你可以直接写成 JSON。我用过的同类工具里很多都支持在项目根目录放一个caveman.json{ title: Acme Inc., subtitle: 新产品正在最后打磨预计 2025 年 6 月上线, accent: #4F46E5, email: helloexample.com, mode: coming-soon, output: dist }如果你用的版本不支持配置文件也别纠结直接改它生成的 HTML 模板也是一样的效果无非是需要手动编辑。2.3 从零写一个可参考的占位页模板万一你用的工具生成出来的默认样式不合口味或者你干脆不想用任何工具就是想自己维护一个模板那下面这份模板可以作为你的起点。它是我实践下来比较稳妥的一套不依赖任何外部库不依赖 CDN离线也能完整显示移动端和桌面端都能看。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleAcme Inc. - 即将上线/title style * { margin: 0; padding: 0; box-sizing: border-box; } body { min-height: 100vh; display: flex; align-items: center; justify-content: center; font-family: -apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, Microsoft YaHei, sans-serif; background: linear-gradient(135deg, #0f172a 0%, #1e293b 100%); color: #f8fafc; text-align: center; padding: 24px; } .card { max-width: 640px; } .logo { font-size: 80px; font-weight: 700; letter-spacing: -3px; line-height: 1.1; } .logo span { color: #4F46E5; } h1 { font-size: 24px; font-weight: 600; margin-top: 32px; } p { font-size: 16px; line-height: 1.8; color: #94a3b8; margin-top: 12px; } .actions { margin-top: 36px; display: flex; gap: 16px; justify-content: center; flex-wrap: wrap; } .btn { display: inline-block; padding: 12px 28px; border-radius: 999px; background: #4F46E5; color: #fff; text-decoration: none; font-size: 15px; transition: transform .2s ease, opacity .2s ease; } .btn:hover { opacity: .9; transform: translateY(-2px); } .btn.ghost { background: transparent; border: 1px solid #475569; } .email-link { display: inline-block; margin-top: 32px; color: #94a3b8; font-size: 14px; } /style /head body div classcard div classlogoAcmespan./span/div h1我们正在准备一个大惊喜/h1 p新产品还在最后的打磨阶段很快就能和你见面。br感谢你此刻的耐心等待。/p div classactions a hrefmailto:helloexample.com classbtn联系我们/a a hrefhttps://github.com/yourname classbtn ghost target_blank relnoopener关注进展/a /div p classemail-link有问题写信给 our-teamexample.com/p /div /body /html这个模板有几个思路值得说。第一是字体栈用了系统字体没有引用任何外部字体文件哪怕用户离线打开也能正常渲染第二是配色只用了一个强调色#4F46E5其他的全是基于暗色背景的灰阶文字页面不管怎么改都不会花第三是按钮都写了语义化的href邮件直接走mailto不依赖 JavaScript。你要改品牌信息只需要动文案、logo 和配色三个地方。2.4 多场景切换404 页和维护页也别忽略占位页不只是coming soon这一种形态。caveman 这类工具通常带mode参数可以切换成 404 页面或者维护页面。三种页面的差别主要在文案上404 页重点是告诉访客你访问的东西不存在维护页重点是告诉访客服务暂时不可用稍后再试。我要提醒的是很多团队做完coming soon就忘了 404 页结果正式上线后用户访问一个拼错的链接看到的还是默认的浏览器错误页。这是很掉价的事情。我的习惯是在部署占位页的时候顺手把404.html也生成一份扔到静态托管的根目录。GitHub Pages、Netlify、Vercel 这些平台都会自动识别404.html作为兜底页面不需要额外配置。3. 完整实操流程从空目录到线上可访问空谈原理没有意思下面我把整条流程完整走一遍。你跟着敲命令就行不需要额外理解太多前置知识。3.1 第一步创建项目目录并初始化我通常会在~/playground或者临时目录里建一个干净的项目文件夹mkdir placeholder-demo cd placeholder-demo npm init -ynpm init -y会生成一个默认的package.json这一行不是必须的但加上它有个好处如果后续你想把生成占位页的命令固化到项目脚本里package.json就是现成的载体。如果你只是临时跑一下这一步可以跳过。3.2 第二步运行 caveman 生成占位页面在项目目录里直接执行npx caveman --output dist --title My Amazing Product执行完之后看一下目录结构正常情况下会多出一个dist文件夹里面至少有一个index.html。这就是生成的完整占位页。如果你传了配置文件它会读配置文件里所有参数如果同时传了命令行参数通常命令行参数的优先级更高。这里有个细节--output dist是把产物放到单独的dist目录而不是直接覆盖项目根目录。这个习惯一定要养成。因为占位页后续是要被正式页面替换掉的产物放在独立目录里之后清掉、换掉都很方便不用在一堆源码文件里大海捞针。我在接手的项目里见过直接把index.html生成在项目末尾、和业务代码混在一起的情况等到真正要替换占位页的时候反而束手束脚。3.3 第三步本地预览确认效果生成完之后立刻本地预览。有很多种方式最简单的npx serve dist或者用 Python 自带的 HTTP 服务器cd dist python3 -m http.server 8080然后用浏览器打开http://localhost:8080。强调一下不要直接双击 HTML 文件在本地打开。虽然这个页面是纯静态的本地双击也能显示但浏览器对file://协议的处理和线上环境有些差异万一你以后往页面里加了外部脚本或者 fetch 请求本地双击是会出问题的。所以从第一步就养成用 HTTP 服务预览的习惯能规避掉后面 90% 的本地好的线上挂了类问题。预览的时候重点检查三件事标题是否显示正确、强调色是否贴合品牌规范、邮箱链接能不能点开。这三个点是最容易出问题的。3.4 第四步部署上线我以最常见的两个平台为例说明部署注意事项先看 GitHub Pages。在 GitHub 仓库的 Settings 里找到 Pages 设置Source 选择分支和目录。如果你已经把dist目录推到了仓库里可以直接选根目录或者/docs目录也可以用 GitHub Actions 来自动构建部署。这里最容易踩的坑是资源路径GitHub Pages 的项目站点是部署在https://用户名.github.io/仓库名/这个子路径下的如果模板里写死了/assets/logo.png这种以斜杠开头的绝对路径会带着/assets/往域名根路径去请求结果 404。解决办法要么让模板使用相对路径要么把页面里所有资源引用改成相对路径。这是我在实际项目里遇到最多的问题占了部署失败案例的一半以上。Netlify 要简单很多。直接把dist文件夹拖到 Netlify 的部署窗口里平台会自动识别并托管。如果你想连接 Git 仓库做持续部署Build Command 留空Publish directory 填dist。Netlify 会把404.html也一并托管所以建议你带着它一起部署。用 Nginx 或者自家服务器的话操作也不复杂rsync -avz --delete dist/ userserver:/var/www/placeholder/把dist下的所有文件同步到站点目录即可。注意 Nginx 的root指令要指到/var/www/placeholder/别指到dist上一层否则路径会多套一层。3.5 接入 CI让占位页在正式页面到来前自动生效实际的团队协作里占位页通常不是手动部署的而是在 CI 流程里自动完成的。一个典型的 GitHub Actions 配置可以长这样name: Deploy placeholder on: push: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - run: npx caveman --output dist --title My Project --mode coming-soon - uses: peaceiris/actions-gh-pagesv4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist这个流程的含义是只要 main 分支有新的提交就自动生成一次占位页并推送到gh-pages分支。等正式页面准备好之后把部署命令从npx caveman换成正式项目的构建命令就行CI 的骨架完全可以复用一个模板不用从零再写一套。4. 常见问题与排查技巧实录整个流程不算复杂但我在实际使用中还是遇到了不少坑。挑几个高频的写在这里给你当速查手册用。4.1 生成的页面样式和本地预览不一致如果你发现同一个dist/index.html本地跑得好好的部署到线上就变样了先别急着怪工具。优先检查是不是资源路径的问题。线上环境如果部署在子目录而页面里引用了绝对路径的 CSS 或图片就会加载失败表现为页面内容还在但所有样式都没了纯文本一排排堆在上面。解决办法是打开浏览器开发者工具切到 Network 面板重新加载页面看哪几个静态资源请求返回了红色的错误状态。逐个修正后再刷新问题一般就消失了。预防的办法是在模板阶段统一使用相对路径引用资源不给部署留隐患。4.2 字体或图片加载不出来占位页如果引用了 Google Fonts 等外部字体服务在部分网络环境下可能加载失败。字体加载这件事有个特性字体文件加载失败不会像 CSS 那样导致页面崩坏浏览器会静默地回退到系统字体。但代价是页面呈现出来的字体和自己设计稿里差别很大尤其中文场景下效果更明显。我的建议很简单除非你设计的页面特别依赖特殊字型否则占位页一律用系统字体栈。不需要为它承担外部网络依赖的风险。如果一定要用特殊字体那就把字体文件下载到本地转成woff2格式放到自己的静态托管里用font-face引用本地路径。4.3 部署后打开是空白页白屏比样式丢失更严重因为连内容都渲染不出来。占位页通常不带什么复杂 JavaScript但如果你修改过模板、加了自定义脚本白屏大概率是脚本报错导致的。打开开发者工具的 Console 面板看红色报错信息。常见的坑有两个一是脚本放在了head里且直接访问了后面的 DOM 节点此时 DOM 还没解析完拿到的是null后续方法调用自然全部报错二是代码里引用了不存在的元素 ID。预防策略是给自定义脚本统一加上DOMContentLoaded事件监听确保 DOM 结构就绪后再执行逻辑。很多静态模板默认没有这一层保护自己加的时候容易漏。4.4 404 页面一直没有生效很多平台确实会自动识别404.html但有一个前提这个文件必须放在站点的根目录。如果你把404.html扔在assets之类的子目录里平台是找不到的。另外本地双击打开404.html时浏览器并不会主动触发 404 渲染逻辑你看到的只是一个普通页面这会让人误以为没配好。实际上部署到服务器后访问一个不存在的路径才会看到平台用这个文件做兜底。4.5 高频问题速查表现象可能原因处理方法线上样式全丢资源路径写成绝对路径 / 部署在子目录改用相对路径或调整部署目录中文变成方块字字体加载失败 / 服务端 MIME 配置错误字体本地化检查 nginx 的 MIME 设置白屏自定义 JS 报错查看 Console给脚本加 DOMContentLoaded部署后 404部署目录不对 /404.html位置错误检查 publish directory确认文件在根目录邮件链接点了没反应mailto:链接里邮箱地址写错检查href属性移动端布局乱缺少 viewport meta在 head 里加meta nameviewport排查这类小问题的通用思路是由外到内分级。先确认线上能否访问、DNS 有没有生效再看页面资源请求状态有没有 404 和超时最后看控制台报错。占位页的东西都很简单走到第三步基本都能找到原因。不要一上来就改模板先定位问题在哪一层能省不少时间。5. 从占位页升级成临时落地页的进阶技巧占位页做到能上线只能算及格。我自己用过一段时间后发现它其实可以临时承担更多职责尤其是当正式页面还没好、但线索收集不能停的时候。5.1 加一个免后端的订阅表单占位页常见的一个变体是收录邮箱、等产品上线了通知我。传统做法是需要写后端接口存邮箱但既然是占位页我们完全没有后端。可以用第三方表单服务比如 Formspree、Getform 这类平台它们会提供一个外部的表单提交地址你在 HTML 里写一个普通的form把action指过去即可form actionhttps://formspree.io/f/yourFormId methodPOST input typeemail nameemail placeholder你的邮箱 required button typesubmit上线了告诉我/button /form用户点击提交后请求会发到第三方服务你再在平台后台配置一个邮件通知就能在零后端的情况下完成线索收集。这一步对独立开发者验证需求来说非常实用哪怕产品还没影子也能抢先攒一批种子用户。5.2 加一个不依赖时区的倒计时很多占位页喜欢放倒计时距离上线还有 XX 天。实现倒计时不难难在服务端和客户端的时区差异。如果直接在前端写到 2025 年 6 月 1 日还剩多少天不同时区的访客看到的秒数会不一样。稳妥的做法是不用日期对象而是固定一个时间戳再通过Intl.DateTimeFormat做本地化展示const target new Date(2025-06-01T00:00:0008:00).getTime(); function updateCountdown() { const now Date.now(); const diff Math.max(0, target - now); const days Math.floor(diff / 86400000); const hours Math.floor((diff % 86400000) / 3600000); // ... 继续计算分钟和秒然后更新到页面 DOM } setInterval(updateCountdown, 1000);关键在于时间字符串里的08:00它把目标时间明确到了固定时区不管访客在哪个时区计算出的剩余时间都是一致的。这个细节不处理好的话你可能在东京看到还有 1 小时在伦敦看到已经上线了情况非常尴尬。5.3 埋点统计从第一天就记录访问占位页也是页面它的访问数据同样有价值。很多人忽略这一点等到正式页面上线才发现没有历史对比数据。我的习惯是在生成占位页的第一天就在head里放进统计脚本不管是开源的 Umami、Plausible还是主流的友盟、百度统计选一个自己顺手的就行。通过埋点你能看到这些数据访客从哪些渠道知道这个网站的、用户停留时间多长、有没有人点击联系邮箱按钮。这些信息在项目早期比什么都值钱——它直接告诉你这个域名有没有人关心宣传渠道有没有带对流量。5.4 把占位页当成项目基建沉淀下来这是我实践下来最想推荐的做法把占位页模板、部署脚本、CI 配置固化成一个团队内部模板而不是每次新建项目都从头来一遍。具体来说你可以在 Git 仓库里建一个placeholder-template仓库维护一份带品牌变量的模板然后写一个简单的脚本接受项目名、主题色、邮箱参数自动生成对应的占位页目录。我个人的实际体会是这个一次性投入大概只有半天但之后的每一次新建项目都省下至少两小时更重要的是它保证了所有项目在上线前的空窗期质量是统一的。团队里的新人接手时也不会因为占位页临时拼凑而踩坑。很多项目最后留给客户的第一个印象恰恰就是这段施工中的时间窗口。一个干净、稳定、快速加载的占位页比一个华丽却三天两头打不开的半成品页面要赢得信任得多。