前言
为什么会有这本书？
2013年，我写下了人生中第一行代码。和很多人一样，我学编程的方式是看视频教程、跟着敲代码、复制粘贴。这样做确实能做出东西——一个ToDo List应用、一个天气预报页面、一个博客系统。教程说做什么，我就做什么。教程说怎么改，我就怎么改。
但有一个问题始终困扰着我：离开教程之后，我什么都不会。
我不知道为什么要用这个库而不是那个库。我不知道为什么文件要这样组织而不是那样组织。我不知道当代码报错时，除了重新看一遍教程、或者在CSDN上复制一段代码碰运气之外，还能做什么。我不知道怎么把一个想法——一个完完全全属于自己的想法——从零变成现实。
这种感觉，就像一个学做菜的人，把菜谱背得滚瓜烂熟，但一旦给他一堆陌生的食材，他就站在厨房里手足无措。他缺的不是菜谱，是对食材本身的理解，是刀工火候的直觉，是“这个菜为什么这样做”的第一性原理。
这本书，就是为那些不再满足于“跟着做”、而是想知道“为什么这样做”的人写的。
这本书在讲什么？
本书围绕一个真实完整的开源项目——THE118™ · 3D 交互式化学元素周期表——展开。项目源码托管在 GitHub，基于 MIT 协议开源。你可以在线体验最终效果：the118.pro。
THE118不是一个“为了教学而编造的玩具项目”。它是一个有真实应用价值的Web应用：展示118个化学元素，支持五种3D布局（表格、球体、螺旋、网格、随机）之间的流畅切换，支持鼠标拖拽旋转和惯性动画，支持元素聚焦和详情查看，支持明暗主题切换。它不使用Three.js或任何第三方3D图形库——所有的3D渲染，完全依靠自定义的4x4数学矩阵运算和CSS的 matrix3d 函数来实现。
在这本书里，我们将从零开始，一步一步把这个项目完整地搭建出来。你会亲手写一个矩阵运算引擎，亲眼看到一个元素周期表从无到有地在你面前诞生。但这本书不只是教你写代码——它会告诉你每一步“为什么这样做”，以及“还有哪些做法，我们为什么选了这一种”。
这是一本“授人以渔”的书。学完之后，你不只会做这个项目，你还会获得一种通用的能力：面对一个未知的技术难题，知道从哪里开始思考、如何拆解问题、怎样做出决策。
这本书适合谁？
如果你符合以下任何一种情况，这本书应该会对你很有帮助：
你是一个前端初学者，已经学过HTML、CSS和JavaScript的基础语法，能写出简单的页面，但不知道怎么把“一堆零散的代码”组织成一个“完整的项目”。你不知道什么是工程化，不知道Git除了 commit 和 push 还能干什么，不知道为什么团队开发需要那么多配置文件。
你是一个自学了一段时间前端的开发者，跟着教程做过几个项目，但总觉得“离开了教程就什么都不会”。你隐约感觉到，自己和“专业前端工程师”之间隔着一层看不见的墙，你想打破它。
你对计算机图形学或者线性代数在实际项目中的应用感到好奇，想看看矩阵到底是怎么让元素在屏幕上转起来的，而不是只在教科书上算行列式。
你想学习“如何设计软件架构”——不只是怎么写一个组件，而是怎么把几十个组件、几十个状态、几十个数据服务组织成一个清晰的、可维护的整体。
你正在准备自己的第一个“拿得出手的作品”——不是教学示例的ToDo List，不是仿写的小米商城，而是一个真正属于你自己的、从零设计并实现的项目，可以自豪地放在简历上。
这本书不适合谁？
坦诚地说，这本书并不适合所有人。如果你属于以下情况，这本书可能会让你感到挫败，我建议你先打好基础再回来看。
你对HTML、CSS、JavaScript完全零基础。 本书不会从“什么是变量”、“什么是DOM”开始讲。如果你还不会写基本的前端三件套代码，请先去学习基础教程，做完几个简单的静态页面，再来读这本书。这不是因为本书的门槛有多高，而是因为我不想浪费你的时间——对着看不懂的术语死磕，不如先去补齐基础。
你想在三天内速成一个项目，应付面试或作业。 这本书不教“最快的做法”，它教“最透彻的做法”。我们会在第6章和第7章停下来，花整整两章的篇幅去写数学工具库——不是因为不会调CSS的 rotateX，而是因为我们要理解底层。如果你追求速成，这本书会让你不耐烦。
你对“为什么要这样做”完全不感兴趣。 如果你的核心诉求是“给我一段能跑的代码就行”，那这本书可能不是最好的选择。这本书最大的篇幅不是用在展示“最终代码”上，而是用在解释我们为什么走到了这里上。每一个技术选型、每一处架构设计，都会展开讨论它的背景、优劣和取舍。
你只想学React，不想碰数学。 本书涉及大量的线性代数——4x4矩阵运算、齐次坐标、变换组合、三角函数。如果你对这些内容完全没有兴趣，只想学React的Hook和组件通信，那我推荐你去看React官方文档或者专门的React教程。本书的数学部分不是点缀，而是核心。
这本书的技术深度
本书的技术覆盖面比较广，但并不追求每个方向的“高级”深度。我们的目标是打通一个完整项目从头到尾的完整链路，让你看到每一个环节的真实样貌。具体来说：
工程化基础：Git、ESLint、Commitlint、Husky、Vite配置、路径别名、环境变量——这些是专业前端开发者的日常工具，本书会在项目初始阶段一次性配好，并解释每个工具的意义。
TypeScript：本书所有代码都用TypeScript编写，不会用 any 来糊弄。但TypeScript本身不是本书的主角——我们不会深入类型体操或高级泛型，我们只用TypeScript做好类型安全这件最基本的事。
线性代数与矩阵运算：这是本书最有特色的部分。我们会从零实现一个4x4矩阵运算库，包括平移、旋转、缩放矩阵的构造，展开循环的矩阵乘法优化，以及复合变换的组合逻辑。不需要你有线性代数的基础——我会用最直观的方式解释每个公式的含义。
React与状态管理：本书使用React 19 + Context + Hooks来构建UI和状态管理。我们会设计四个独立的Context来管理不同的状态域，讨论Provider的嵌套顺序、惰性初始化和性能优化策略。
架构设计：这是本书的另一个核心。我们会先搭建一个传统的分层架构，然后在书的第五部分，主动审视它的缺陷，引入FSD（Feature-Sliced Design）进行重构。你会看到：架构不是一开始就设计完美的，它是演化出来的。
测试与部署：本书会为数学工具和布局算法编写单元测试，并把测试挂到Git Hooks上。最后，我们会用GitHub Pages把项目部署上线，绑定自定义域名。
如何使用本书？
这本书不是一本“地铁读物”——你不会在通勤路上翻两页就能学到东西。它需要你坐在电脑前，打开编辑器，跟着每一章的步骤亲手写代码。
每一章都依赖前面章节的成果，所以建议你按顺序阅读，不要跳章。如果你在某一章卡住了，可以先去GitHub仓库查看对应阶段的源码，对照着找问题。
每一章末尾都有一个“扩展思考”或者“调试彩蛋”——这是留给你的练习题。它们不是选做的，而是帮助你巩固理解的必经之路。
书中的代码并不是“最终版本”。在第16章到第19章的重构部分，我们会主动修改甚至推翻前面的代码。这可能会让你觉得“之前的努力白费了”，但请相信——这不是浪费，这是演化。真实世界的软件就是这样，没有一蹴而就的完美设计。
善用Git。 在每一章结束后，commit你的代码。这样，当你读到重构章节、需要大幅改动代码时，你随时可以回退到之前的版本，或者查看“重构前”和“重构后”的差异。Git不只是存档工具，它是你的学习笔记。
致谢
这本书的诞生，离不开很多人的帮助。
感谢凯尔·辛普森的《你不知道的JavaScript》——这套书教会我，技术写作可以像侦探小说一样引人入胜。你会在本书的叙述风格中，看到它深深的影子。感谢查尔斯·佩措尔德的《编码》——它证明了一件事：再复杂的技术，只要从第一性原理出发，都能被清晰地解释。本书的“不教怎么用、教为什么这样设计”的理念，就来源于此。
感谢THE118项目的所有早期体验者和反馈者。你们在项目还处于粗糙原型阶段时就开始关注它，并提出了宝贵的改进建议。
感谢你——本书的读者。你选择了一条更难的路：不满足于“能跑就行”，而是追问“为什么能跑”。在这个追求速成的时代，这是一种稀缺而珍贵的品质。
最后感谢我最敬爱的母亲——在我人生最迷茫的的时期，是她在一直鼓励着，支持着我！我才得以对本书进行撰写工作。
获取更多帮助与反馈
本书的配套源码在 GitHub 上开源，你可以在线体验最终效果：the118.pro。如果你在阅读过程中发现了错误——无论是技术错误、拼写错误还是逻辑错误——欢迎提交Issue或Pull Request。
如果你在使用本书或THE118项目的过程中遇到任何问题，或者有任何建议、合作意向，欢迎通过以下方式与我联系：
- 电子邮箱：emmakyitt@gmail.com
- GitHub：github.com/emmakyitt
我无法保证立刻回复每封邮件，但我一定会认真阅读每一封来信。
由于作者水平和学识有限，书中难免存在疏漏、错误或表述不够准确之处。本书所涉及的技术栈——React、TypeScript、Vite、FSD架构等——均处于快速迭代之中，书中内容虽力求与当前最新版本保持一致，但技术的演进速度往往快于书籍的出版周期。因此，部分细节在您阅读时可能已发生变化，敬请留意相关技术的官方文档以获取最新信息。
本书的写作过程，也是作者自身学习和反思的过程。每一次重读已经写下的章节，都能发现可以改进的地方。这正是软件工程的魅力所在：没有完美的代码，也没有完美的书籍，只有不断迭代、不断完善的追求。
敬请广大读者不吝批评指正，并提出宝贵意见。你们的反馈，将是本书持续改进的最大动力。
好了，让我们开始吧。翻开下一页，第1章见。
emmakyitt
2026年5月