简介这是一份基于JavaScript开发的互动猜谜游戏完整项目适合前端初学者及对游戏开发感兴趣的开发者用来练习事件处理、页面元素操作与游戏逻辑设计。资源共8个文件涵盖层叠样式表、脚本、页面、配置文件说明等多种类型压缩包整体仅1.12兆字节结构紧凑便于快速下载学习。项目通过监听用户点击触发游戏利用随机函数生成谜题通过条件判断验证答案并实时刷新页面内容同时可结合浏览器本地存储保存得分或进度完整呈现了从界面渲染到交互反馈的典型流程。已有138人学习下载包内还包含代码规范配置与说明文档能够帮助读者规范编码风格、理解项目目录安排是巩固前端基础、积累实战经验的一份轻量级参考。1. 猜谜游戏原生JavaScript实现的状态驱动小应用刚拿到这份猜谜游戏源码时我以为撑死就是对着一组数组做判断的小玩具实际把代码啃完才发现它在不到十个文件里把题库、状态机、渲染、持久化四层拆得干干净净。整个游戏没有一个框架依赖但出题去重、提示扣分、限时计时的完整判定链路全都能在断网状态下跑通。游戏玩法很简单——屏幕中央给出一条谜面你在输入框里填成语匹配就得分拿不准可以点提示每个提示会折损基础分答错不扣分但会记录次数一局十题跑完把名字写进本地排行榜。对前端学习者来说它是一个能直接跑起来的原生JavaScript实战标本对想二次开发的人来说它最值得看的反而是那层极简状态机怎么写才不容易在加功能时翻车。下面按固定的顺序来先讲架构和数据流怎么分层再逐段拆核心模块的判定逻辑然后是踩过的坑和运行方式最后聊怎么在不破坏现有逻辑的前提下顺手加一个新玩法。2. 架构与数据流题库、状态与渲染的三层分离2.1 技术选型为什么原生JavaScript就够用这个项目的场景决定了它不需要重型框架。游戏交互集中在单个输入框、几个按钮和一块计分面板上DOM规模很小手动操作和直接绑定事件的代码量完全可控。引入Vue或React反而多了一层虚拟DOM调度题库和状态要包在组件里传递对这样一个体量的项目属于额外负担。Vite在这里的角色只是开发服务器和打包器不参与业务逻辑。它提供的热更新让改完代码后浏览器自动刷新调试体验比裸写静态页面舒服很多。生产环境跑出来的产物是一堆纯静态文件扔到任意静态服务器或对象存储上都能跑不需要Node服务常驻。模块组织上是标准的ES Module方案四个js文件按职责切分data.js只放题库纯数据game.js持有全部游戏逻辑和状态ui.js负责DOM读写storage.js封装本地存储。这样切有一个实际收益——将来想换界面框架时game.js和storage.js一行都不用动只重写ui.js。2.2 目录结构六个文件承担四条职责guess-game/ ├── index.html # 唯一页面骨架 ├── package.json # 依赖与npm脚本 ├── vite.config.js # 开发服务器与构建配置 ├── css/ │ └── style.css # 卡片、动画、响应式布局 └── js/ ├── data.js # 成语题库纯数据 ├── game.js # 游戏状态机与核心规则 ├── ui.js # DOM操作与事件绑定 └── storage.js # localStorage封装index.html里只放根容器和音效元素所有界面都由ui.js根据状态动态生成。css/style.css用固定宽度的卡片布局配合min-height保证提示内容增减时页面不跳动。vite.config.js只做了两件小事开发端口和base: ./——这个配置很关键能让构建产物在子目录或file协议下都能正确加载资源。四个js文件的依赖关系是单向的ui.js依赖game.js暴露的状态和动作game.js依赖data.js的题库和storage.js的读写方法。谁都不反向依赖所以单独替换任何一个文件时不会牵连其他模块。2.3 单向数据流从用户输入到界面刷新游戏的状态集中在game.js的模块级state对象里它是整个应用唯一可信的数据源。每次用户操作——提交答案、使用提示、跳过题目——都会走进game.js的对应函数函数检查当前状态、计算变更、更新state然后调用ui.js的渲染函数一次性重绘整个界面。// game.js 顶部模块级状态 const state { mode: classic, // 游戏模式预留扩展位 pool: [], // 待出题池洗牌后挨个取 currentIndex: -1, // 当前题在pool中的下标 score: 0, // 累计得分 usedTips: 0, // 本题已用提示次数用于扣分 wrongAttempts: 0, // 本题答错次数仅记录展示 };state被设计成扁平结构没有嵌套对象原因是避免多层引用带来的隐式共享问题。一个搜索题解时最常见的翻车现场就是状态分散在多个变量里改了一个忘了另一个界面和数据对不上。所有动作函数都遵循同一套流程读取当前状态判断是否允许执行计算新值覆盖旧值触发render。数据流是肉眼可见的单向循环用户点按钮 → 事件回调 →game.js的action函数 → 修改state→ui.render(state)→ 重新绘制DOM。想追踪一个bug时只需要沿着动作函数找它改了哪几个字段再去渲染函数确认这些字段对应的DOM区域不用在整个代码库里来回跳。3. 核心模块拆解出题、判分与排行榜的完整链路3.1 题库结构谜面、答案、难度与提示的字段设计题库是项目的血液它的结构决定了判分逻辑能写得多简洁。每条题目只存四样东西唯一id、难度等级、谜面描述和按顺序排列的提示数组。每个难度档存放约三十条成语整体规模控制在九十条以上既保证一局十题不重样又不至于让数据文件大到影响加载。// data.js 题库片段 export const questions [ { id: 1, difficulty: 1, // 1: 简单 2: 中等 3: 困难 clue: 形容做事极其认真连最细微的地方也不疏忽, answer: 一丝不苟, tips: [ 第一个字是『一』, 常用来夸人批改作业、核对账目很仔细, 最后一个字与『狗』同音 ] }, // 每个难度约 30 题共 90 ];id用于跨存储匹配比如恢复游戏快照时通过id从全量题库里反查出原题对象。difficulty直接映射基础分简单题10分、中等题20分、困难题30分。tips是数组而非字符串因为扣分规则按条数计算同时UI层需要逐条展示。这里有个设计取舍值得学习谜面刻意用描述性文字而不用谜语格式。描述性谜面让答案分布更可控避免出一道谁都猜不出来的冷谜提示数组的顺序也决定了难度递增的体验——第一条给最模糊的线索后面越来越接近答案每个提示对应一次明确的扣分。3.2 出题与去重Fisher-Yates洗牌与待出题池一局游戏从题库中抽取十题最怕的是十分钟里遇到三道同一成语。解决方案不复杂游戏开始时把整个题库拷贝一份用Fisher-Yates算法原地洗牌然后按顺序从头取出题每答完一题就移动指针或从池中移除。这样一轮内不可能出现重复题除非题库总量本身就少于十题。function shuffle(arr) { for (let i arr.length - 1; i 0; i--) { const j Math.floor(Math.random() * (i 1)); [arr[i], arr[j]] [arr[j], arr[i]]; } return arr; } function startGame() { state.pool shuffle([...questions]); state.currentIndex 0; state.score 0; state.usedTips 0; renderQuestion(); }Math.floor(Math.random() * (i 1))生成从0到i的随机下标每次交换当前位置元素与随机位置元素。因为随机数可能等于i所以元素也有机会留在原地这是洗牌的正确行为。注意[...questions]浅拷贝了题库——必须拷贝直接shuffle原数组会污染全局题库下次开局时已经打乱了无法回到原始顺序。currentIndex在每次答对或跳题后加一当它等于pool.length时说明十题完毕游戏进入结算。若想实现“答错也继续出同一题”只需要在答错分支里不移动currentIndex这个状态机天然支持这种规则。3.3 判分与扣分规则一次提交里发生的三次运算提交答案的处理函数是整条链路的核心它要同时处理答案匹配、难度分值计算、提示扣分三件事。这里的关键设计是扣分不与基础分做百分比运算后再加总而是先算基础分再逐条扣保证规则可解释——用户能明确知道“用了两个提示扣了多少分”。function checkAnswer(input) { const q state.pool[state.currentIndex]; if (!q) return null; // 池子已空或状态异常 if (input.trim() ! q.answer) { state.wrongAttempts; return { ok: false, reason: wrong }; } const base { 1: 10, 2: 20, 3: 30 }[q.difficulty]; const deduction Math.round(base * 0.3 * state.usedTips); const gained Math.max(0, base - deduction); state.score gained; return { ok: true, gained }; }input.trim()负责清除首尾空格中文输入法偶尔在确认后残留空格这一步能避免明明答对了被判定失败。扣分公式的基准是单个提示扣除基础分的30%三条提示最多扣掉90%这个比例保证玩家不会因使用提示直接得零分也不会出现负数。function useHint() { const q state.pool[state.currentIndex]; const nextIdx state.usedTips; // 当前应取第几条 if (nextIdx q.tips.length) return null; // 提示耗尽 state.usedTips; return q.tips[nextIdx]; }useHint返回的是提示字符串而非下标由ui.js负责挂载到DOM上。这里把usedTips放在全局状态而不是buttons数组的length上有个实际好处——恢复快照时不需要重新遍历DOM直接从state里读出数字即可。3.4 排行榜持久化localStorage的容错封装排行榜模块体积最小但最容易踩坑。直接调localStorage.getItem然后JSON.parse在用户清空站点数据或处于隐私模式时会抛异常必须包一层try/catch。saveRank负责追加、排序、截断三步操作把榜单控制在十条以内。const KEY guess_game_rank; export function loadRank() { try { return JSON.parse(localStorage.getItem(KEY)) || []; } catch { return []; } } export function saveRank(entry) { const list loadRank(); list.push(entry); list.sort((a, b) b.score - a.score); localStorage.setItem(KEY, JSON.stringify(list.slice(0, 10))); }entry的结构由调用方拼好包含玩家名、分数和结束时间戳。排序放在存储层而不是UI层保证不管从哪个入口调用saveRank拿到的榜单永远是有序的。截断操作放在排序之后而非之前否则超过十条时新纪录可能被数组越界挤掉。使用时间戳存而不是日期字符串是为了规避不同浏览器对日期格式解析不一致的问题这个坑在后面的避坑章节展开讲。4. 常见问题与避坑本地调试与持久化踩过的五个坑4.1 输入法回车导致答案误判现象在输入框敲入拼音后按回车确认候选词答案会瞬间被提交一次有时候显示“回答错误”但明明还没点提交按钮。原因keydown事件在输入法组词状态下也会触发此时event.isComposing为true代码没有过滤这个状态把“确认拼音”当成了“提交答案”。inputEl.addEventListener(keydown, (e) { if (e.isComposing) return; // 输入法组词中忽略一切按键 if (e.key Enter) checkAnswer(); });解决在回车判断之前检查e.isComposing为true时直接return。这个坑中文应用几乎必踩团队里新来的同事第一次接手搜索框逻辑时总会再犯一次。4.2 刷新一下就白玩内存状态没有恢复现象打了一局四道题、斩获七十分手一滑按了F5游戏回到初始状态分数和当前题号全部清零。原因state对象活在内存里页面刷新后JavaScript重新执行一切都得从头开始。项目本身支持localStorage持久化但没有把“游戏进行中的快照”也存进去。解决在每次得分或换题时同步一份快照到localStorage页面加载时先尝试恢复再继续。快照里只存pool中各题的id和currentIndex页面刷新后用id映射回原题对象避免把整个题库序列化进存储。4.3 同一道题一局里出现两次现象玩到第五题时遇到了第一题刚答过的成语让玩家觉得题库有bug。原因早期的抽题逻辑用的是Math.random()直接取下标抽完不标记同一题会被重复抽中。这种随机不是无放回的题库越大重复概率越高。解决回到第3.2节的洗牌方案。开局时全量洗牌再顺序出题完全杜绝一轮内的重复。如果以后题库扩充到上千条可以改成“取前N条后重新洗牌窗口”的策略平衡重复度和随机感。4.4 提示条数变化把布局震飞了现象点击“使用提示”后卡片内容变高提交按钮被往下挤鼠标点下去时已经对不准位置了。原因提示区是动态追加DOM节点外层容器高度没预留余量内容高度变化后整个卡片FC的布局重新计算。解决对提示区和错误提示区设置min-height固定高度的同时允许内容超出。卡片主体用flex纵向布局把按钮区域放到flex-shrink: 0的底部不管中间内容多长按钮永远在可视区域内。4.5 排行榜时间显示NaN现象排行榜上的日期显示成“NaN/NaN/NaN”但分数和名字都正常。原因存储时用了YYYY-MM-DD HH:mm:ss格式的字符串渲染时执行new Date(2024-06-01 10:20:30)。部分浏览器引擎不认这种中间带空格的格式直接返回Invalid Date。解决存储一律用Date.now()返回的数字时间戳展示时再格式化。数字格式不依赖本地化解析规则跨浏览器、跨平台都不会出现这个玄学问题。5. 运行与部署从npm install到生成静态站点5.1 本地环境Node版本与依赖清单项目跑起来只有一个前置依赖Node.js。推荐使用18及以上版本包管理器和构建工具都兼容这个基线。仓库没有锁第三方运行时依赖核心的Vite和原生ES Module都不需要额外原生模块编译所以安装过程很省心。node -v npm -v如果node -v输出v18.x或更高直接进入下一步。低于16的话建议先升级老版本Node跑Vite会报文件监听相关的错误那个错误信息不太友好容易让人误判是项目本身的bug。5.2 安装与启动三条命令跑起来npm install npm run devnpm install会把Vite拉到node_modules里。装完后执行npm run dev终端会输出一个localhost:5173的地址浏览器打开就是游戏首页。开发模式下Vite会拦截模块请求并按需转译所以第一次打开稍慢之后每次刷新基本是秒开。验证是否跑通的标准页面能随机出第一题输入正确答案后分数从0变成对应分值排行榜能写入一条记录。走到这一步说明数据层、状态层和渲染层全部正常联通。5.3 构建部署dist目录的三种放法npm run build构建完成后输出dist/目录里面是压缩后的index.html、css和js。因为vite.config.js里设置了base: ./产物里所有资源路径都是相对路径这让部署变得非常灵活。三种常用放法扔到Nginx的静态站点目录配一个location指向dist文件夹放到对象存储的Bucket并开启静态网站托管按流量计费、无需维护服务器或者直接压缩dist文件夹发给同事本地解开用任意静态服务器起服务就能玩。注意不要用浏览器直接双击index.html打开——ES Module在file://协议下会被浏览器安全策略拦截这是最容易让新手卡壳的地方。5.4 常见启动问题端口占用与构建缓存残留Vite默认端口被占用时会提示并自动尝试下一个端口终端日志里有Port 5173 is in use, trying another one...。如果想让端口固定在vite.config.js里加server: { port: 3000, strictPort: true }strictPort设为true后端口被占会直接报错退出适合写自动化脚本时用。另一个隐蔽问题是构建缓存残留。改过data.js等核心文件后npm run build默认复用node_modules/.vite里的缓存偶尔会出现“代码明明改了产物没更新”的错觉。清理方式是把dist和node_modules/.vite删掉重新构建或者执行npx vite build --force强制刷新缓存。6. 二次开发十分钟加一个连击挑战模式6.1 改造思路与核心代码原生JavaScript项目加功能的关键是顺着状态机扩展而不是往事件回调里堆代码。以加一个“限时连击模式”为例经典模式是一题不限时、答对得分挑战模式每题限时15秒倒计时内答对进入下一题连续答对十次触发额外加分。先在state里补两个字段mode和combo再新增一个启动函数和计时器管理函数。计时器句柄必须存到state上否则模式切换时旧计时器不会被清理会出现两个计时器同时跑、分数跳变的诡异现象。function startRush() { state.mode rush; state.combo 0; state.currentIndex 0; clearInterval(state.timer); // 清掉可能残留的旧计时器 state.timer setInterval(() { if (state.mode ! rush) return; // 模式切换后直接退出 failQuestion(); // 超时判负自动换题 }, 15000); } function onCorrect(q) { if (state.mode ! rush) return; state.combo; if (state.combo % 10 0) { state.score 30; // 每10连击额外奖励 } }改造时只在checkAnswer的答对分支里多调用一次onCorrect经典模式的原始流程完全不用动。向外暴露的接口保持兼容ui.js需要改的只有“挑战模式下显示倒计时”这一个渲染点。6.2 验证方法改完不要急着发布按这四条走一遍回归经典模式跑完十题确认原有判分和提示扣分没被连击逻辑干扰挑战模式连续答对十题确认额外三十分只加一次把计时器临时改成两秒确认超时会自动换题且不会重复触发换题逻辑在挑战模式中途回到经典模式确认旧计时器被清除不会出现分数跳加。从那以后我每次给这个游戏加功能都强制先把状态机跑一遍、把可能留下两个计时器的地方全查一遍再动手写代码这套习惯帮我避掉了无数DIY改动引发的离奇bug希望帮到你。本文还有配套的精品资源点击获取