企业官网建设流程全解析

prehistoric-animal-museum是一个免费开源的双语 3D 古生物博物馆，孩子和家长可以一起在海、陆、空三大展厅里 360° 观察剑龙、沧龙、翼龙等史前动物。本指南带你用npm ci与npm run dev两条命令，5 分钟完成 prehistoric-animal-museum 的本地开发环境搭建并启动开发服务器，无需任何额外配置。

🦕 项目速览：本地跑起来后能看到什么

这是一个"安静地、仔细地看动物"的博物馆：

• 🌍陆、海、空三大展厅：从剑龙到沧龙，再到翼龙，共 25+ 种史前动物
• 🌐中英双语：跟随设备语言自动切换，也可随时手动切换
• 🔊旁白不自动播放：由孩子主动选择收听，配家长资料卡片
• 🔐无登录、无广告、无分析脚本：所有模型与素材均为静态资源

下面就是本地运行后，陆展厅剑龙展项的实际效果：

📋 本地开发环境要求

开始之前，只需确认一个东西——Node.js 版本：

💡小建议：如果你使用nvm管理 Node 版本，进入项目目录后执行一次nvm use即可自动切换到.nvmrc指定的版本，省去手动核对。

用node -v确认版本满足要求，就可以进入下一步。

🚀 三步跑起来:clone → npm ci → npm run dev

第一步:获取仓库

在终端中执行：

git clone https://gitcode.com/gh_mirrors/pr/prehistoric-animal-museum cd prehistoric-animal-museum

第二步:npm ci 安装依赖

npm ci

为什么用npm ci而不是npm install？

• ✅ 严格按照 package-lock.json 安装，版本 100% 可复现，避免"在我机器上是好的"这类问题
• ⚡ 比npm install更快，且不会意外修改 lock 文件
• 📦 一次性装好 React 19、Three.js、Vite 等全部依赖（见 package.json）

第三步:npm run dev 启动开发服务器

npm run dev

这条命令实际执行的是 package.json 中的vite脚本，启动Vite 开发服务器，默认地址为http://localhost:5173，用浏览器打开即可开始逛博物馆：

• 🖱️ 拖拽旋转 3D 模型，滚轮或双指缩放
• 🌐 右上角可切换 中文 / English，选择会被记住
• 🔁 修改代码后页面热更新，无需手动刷新

启动成功后，你会看到这样的海洋展厅——沧龙在 3D 海水中游弋，左侧是中文介绍卡片：

🌲 开发模式下，vite.config.ts 会将virtual:scale-encounter-entry别名解析为"启用版"入口，因此npm run dev中可以看到完整的"体量对照"等体验功能。

❓ 常见问题排查

🧭 项目结构导航（新手向）

第一次接触代码，可以从这几个目录入手：

想深入了解某只动物的完整资料，打开 src/content/animals/stegosaurus/ 就能看到模型、图片、音频和来源说明一应俱全。

✅ 开发后还能做什么

改完代码后，建议按 README.md 中的清单运行项目检查：

npm run lint # ESLint 代码风格检查 npm run typecheck # TypeScript 类型检查 npm test -- --run # Vitest 单元测试 npm run build # 生产构建 npm run test:e2e # Playwright 端到端测试

最后看看空展厅——古神翼龙在湖畔天空中展开皮膜翅膀，这正是你在本地开发中随时能调出来的 3D 场景：

🎉 结语

到这里，prehistoric-animal-museum 的本地开发环境就搭建完成了：Node.js 22.13.0+ →git clone→npm ci→npm run dev，5 分钟即可在自己的机器上运行这座 3D 古生物博物馆，并随时修改代码、热更新查看效果。

如果你准备提交贡献，请先阅读 CONTRIBUTING.md 了解代码与内容的许可边界；想提议新增一种史前动物，则从 ANIMAL_AUTHORING_GUIDE.md 开始。祝开发愉快，期待你的贡献让博物馆更完整！