【Cursor _RubicsCube Diary 1】Node.js；npm；Vite

================================================================================

魔方公式可视化网站 - 启动项目详细步骤

⚠️ 重要提示：这是一个需要编译的现代Web项目，不能直接打开HTML文件！

必须按照以下步骤操作。

================================================================================

第一步：检查环境

1.1 检查是否已安装 Node.js

打开命令提示符（cmd）或 PowerShell
输入命令：node -v
如果显示版本号（如 v18.x.x 或 v20.x.x），说明已安装，跳到第二步
如果没有显示或报错，需要先安装 Node.js

1.2 安装 Node.js（如果未安装）

访问官网：https://nodejs.org/
下载 LTS（长期支持）版本
运行安装程序，全部选择默认选项
安装完成后，重启命令提示符
再次运行 node -v 确认安装成功

1.3 检查 npm（Node.js 自带，通常不需要单独安装）

输入命令：npm -v
应该显示版本号（如 9.x.x 或 10.x.x）

================================================================================

第二步：打开项目文件夹

方法1：使用文件资源管理器

打开文件资源管理器
导航到项目文件夹：
D:\Users\KRATZDISTELN\Desktop\STEFANO_Programs_Rubics_Cube
在文件夹空白处，按住 Shift 键，然后右键点击
选择"在此处打开 PowerShell 窗口"或"在此处打开命令窗口"

方法2：使用命令提示符

按 Win + R 键
输入 cmd，按回车
输入以下命令切换到项目目录：
cd /d D:\Users\KRATZDISTELN\Desktop\STEFANO_Programs_Rubics_Cube

方法3：使用 PowerShell

按 Win + X 键
选择"Windows PowerShell"或"终端"
输入以下命令切换到项目目录：
cd D:\Users\KRATZDISTELN\Desktop\STEFANO_Programs_Rubics_Cube

================================================================================

第三步：安装项目依赖

3.1 确认当前位置

在命令窗口中，你应该看到类似这样的路径：
PS D:\Users\KRATZDISTELN\Desktop\STEFANO_Programs_Rubics_Cube>
或者：
D:\Users\KRATZDISTELN\Desktop\STEFANO_Programs_Rubics_Cube>

3.2 安装依赖包

输入命令：npm install
按回车执行
等待安装完成（可能需要1-5分钟，取决于网络速度）
你会看到很多输出信息，最后应该显示类似：
added XXX packages in XXs

3.3 如果安装很慢或失败

可以使用国内镜像源加速：
npm config set registry https://registry.npmmirror.com
然后重新运行：npm install

3.4 验证安装

安装完成后，检查是否有 node_modules 文件夹
如果看到 node_modules 文件夹，说明安装成功

================================================================================

第四步：启动开发服务器

4.1 启动服务器

在命令窗口中输入：npm run dev
按回车执行
等待几秒钟，你会看到类似这样的输出：

VITE v5.x.x ready in XXX ms

➜ Local: http://localhost:5173/

➜ Network: use --host to expose

4.2 如果端口被占用

Vite 会自动使用下一个可用端口（如 5174, 5175 等）
注意查看实际显示的端口号

4.3 保持命令窗口打开

⚠️ 重要：不要关闭这个命令窗口！
关闭窗口会停止开发服务器
如果需要停止服务器，按 Ctrl + C

================================================================================

第五步：在浏览器中打开网站

5.1 打开浏览器

推荐使用 Chrome、Edge 或 Firefox
打开浏览器

5.2 访问网站

在地址栏输入：http://localhost:5173
或者点击命令窗口中显示的链接
按回车访问

5.3 确认网站正常运行

你应该看到：
- 深色背景的网页
- 顶部有"魔方公式可视化"标题
- 左侧有3D魔方模型（可以鼠标拖拽旋转）
- 右侧有公式输入框和算法库

5.4 如果页面空白或报错

检查命令窗口是否有错误信息
尝试刷新浏览器（F5）
检查浏览器控制台（F12）查看错误信息

================================================================================

第六步：使用网站

6.1 输入公式

在右侧"公式输入"框中输入公式，例如：R U R' U'
点击"执行"按钮
观察左侧3D魔方的旋转动画

6.2 使用算法库

在右侧"算法库"面板中
选择"CFOP法"或"桥式法"标签
展开分类，点击任意公式即可自动执行

6.3 交互控制

鼠标左键拖拽：旋转3D视角
鼠标滚轮：缩放魔方
鼠标右键拖拽：平移视角

6.4 重置魔方

点击"重置"按钮，魔方恢复到已还原状态

================================================================================

停止服务器

当你想停止开发服务器时：

回到命令窗口
按 Ctrl + C
确认停止（输入 Y 或直接按回车）

================================================================================

常见问题解决

问题1：提示 "npm 不是内部或外部命令"

解决：

Node.js 没有正确安装
重新安装 Node.js，确保勾选"添加到PATH"
重启命令窗口

问题2：npm install 报错或很慢

解决：

使用国内镜像：npm config set registry https://registry.npmmirror.com
清除缓存：npm cache clean --force
重新运行 npm install

问题3：端口 5173 已被占用

解决：

Vite 会自动使用其他端口
查看命令窗口显示的实际端口号
或者修改 vite.config.ts 指定其他端口

问题4：页面显示空白

解决：

检查命令窗口是否有错误
按 F12 打开浏览器控制台查看错误
尝试清除浏览器缓存
确保所有依赖已正确安装

问题5：3D魔方不显示

解决：

检查浏览器是否支持 WebGL
尝试更新浏览器到最新版本
检查显卡驱动是否最新

问题6：公式执行后魔方没变化

解决：

检查公式格式是否正确
确保使用标准符号（R, U, F, L, D, B）
检查浏览器控制台是否有错误

问题7：想要修改代码后自动刷新

解决：

开发服务器已启用热更新
修改代码后，浏览器会自动刷新
无需手动操作

================================================================================

快速命令参考

切换到项目目录

cd D:\Users\KRATZDISTELN\Desktop\STEFANO_Programs_Rubics_Cube

安装依赖（首次运行）

npm install

启动开发服务器

npm run dev

构建生产版本

npm run build

预览生产版本

npm run preview

设置国内镜像源（加速下载）

npm config set registry https://registry.npmmirror.com

清除 npm 缓存

npm cache clean --force

================================================================================

项目结构说明

项目文件夹包含：

src/ - 源代码文件夹
docs/ - 文档文件夹
log/ - 开发日志
_User/ - 用户文档（本文件所在位置）
package.json - 项目配置文件
index.html - HTML入口文件
vite.config.ts - Vite配置文件

重要文件：

src/App.tsx - 主应用组件
src/components/CubeVisualizer.tsx - 3D魔方组件
src/utils/cubeLogic.ts - 魔方逻辑
src/data/algorithms.ts - 算法数据

================================================================================

技术支持

如果遇到问题：

查看 log/开发日志.txt 了解项目开发过程
查看 docs/快速开始.md 获取更多帮助
检查浏览器控制台（F12）的错误信息
确认 Node.js 和 npm 版本是否兼容

项目要求：

Node.js 版本：16.x 或更高
npm 版本：7.x 或更高
现代浏览器（Chrome、Edge、Firefox 最新版本）

================================================================================

更新日志

2024-12-19\] 创建启动步骤文档 * 详细说明从零开始启动项目的每一步 * 包含常见问题解决方案 * 提供快速命令参考 ## ================================================================================ ## 魔方公式可视化网站 - 开发日志 ### \[2024-12-19\] 项目初始化 1. 创建项目基础结构 * 创建 package.json，配置 React + TypeScript + Vite + Three.js * 创建 tsconfig.json 和 tsconfig.node.json，配置 TypeScript * 创建 vite.config.ts，配置 Vite 和 React 插件 * 创建 index.html，设置基础 HTML 结构 2. 创建样式系统 * 创建 src/index.css，定义全局样式和 CSS 变量（深色模式） * 定义颜色变量： * --bg-primary: #0a0a0a (主背景) * --bg-secondary: #1a1a1a (次背景) * --bg-tertiary: #2a2a2a (第三背景) * --text-primary: #ffffff (主文本) * --text-secondary: #b0b0b0 (次文本) * --accent: #4a9eff (强调色) * --border: #333333 (边框) 3. 创建主应用组件 * 创建 src/main.tsx，React 应用入口 * 创建 src/App.tsx，主应用组件 * 创建 src/App.css，应用布局样式 * 实现响应式布局（桌面端和移动端） 4. 实现魔方核心逻辑 * 创建 src/utils/cubeLogic.ts * 定义颜色常量（白、黄、红、橙、蓝、绿） * 实现 CubeState 类型（6个面的状态） * 实现 createSolvedCube() - 创建已还原的魔方 * 实现 rotateFace() - 旋转单个面（顺时针90度） * 实现所有基础旋转： * rotateR / rotateRPrime - 右层旋转 * rotateU / rotateUPrime - 上层旋转 * rotateF / rotateFPrime - 前层旋转 * rotateL / rotateLPrime - 左层旋转 * rotateD / rotateDPrime - 下层旋转 * rotateB / rotateBPrime - 后层旋转 * 实现 applyRotation() - 应用旋转操作（支持 R2, U2 等） 5. 实现公式解析器 * 创建 src/utils/formulaParser.ts * 实现 parseFormula() - 解析公式字符串（如 "R U R' U'"） * 支持标准符号：R, U, F, L, D, B 及其 ' 和 2 变体 * 实现 isValidFormula() - 验证公式有效性 6. 实现3D魔方可视化组件 * 创建 src/components/CubeVisualizer.tsx * 使用 @react-three/fiber 和 @react-three/drei * 实现 Cubie 组件 - 单个小方块（6个面） * 实现 RubiksCube 组件 - 完整3D魔方（27个小方块） * 实现颜色映射逻辑（根据魔方状态显示正确颜色） * 实现公式执行逻辑（逐步动画，每步300ms） * 添加 OrbitControls - 鼠标交互控制 * 添加光照系统（环境光、方向光、点光源） * 创建 src/components/CubeVisualizer.css 7. 实现公式输入组件 * 创建 src/components/FormulaInput.tsx * 输入框组件 * 提交和重置按钮 * 错误提示 * 帮助文本（支持的符号说明） * 创建 src/components/FormulaInput.css 8. 实现算法库组件 * 创建 src/components/AlgorithmLibrary.tsx * 标签页切换（CFOP法 / 桥式法） * 可折叠分类列表 * 点击公式自动执行 * 创建 src/components/AlgorithmLibrary.css 9. 收集和整理算法数据 * 创建 src/data/algorithms.ts * CFOP法算法： * F2L (前两层): 42个公式 * OLL (顶层朝向): 57个公式（分类：点、线、L型、T型、C型、其他） * PLL (顶层换位): 21个公式（分类：角块、棱块、角块+棱块） * 桥式法算法： * 左桥: 6个基础公式 * 右桥: 6个基础公式 * CMLL: 42个公式 * LSE: 多个公式（EO、UL/UR、M层） 10. 创建文档 * 创建 README.md - 项目说明文档 * 创建 docs/CFOP算法公式.md - CFOP法完整公式库 * 创建 docs/桥式法算法公式.md - 桥式法完整公式库 * 创建 docs/快速开始.md - 使用指南 11. 创建配置文件 * 创建 .gitignore - Git 忽略文件配置 12. 代码优化 * 移除未使用的导入（useFrame, useRef） * 清理代码，确保无 lint 错误 ### ================================================================================ \[2024-12-19\] 问题修复 问题：用户直接打开 index.html 文件，网页显示空白 原因分析： 1. 这是一个 Vite + React + TypeScript 项目 2. index.html 中的脚本是 TypeScript (.tsx)，需要编译 3. 直接打开 HTML 文件无法处理模块导入和 TypeScript 4. 必须通过 Vite 开发服务器运行 解决方案： 1. 创建开发日志文件（当前文件） 2. 检查并确保所有文件正确配置 3. 提供正确的启动说明 4. 可能需要添加一些错误处理和提示 操作记录： * 创建 log/开发日志.txt 文件，记录所有开发操作 * 检查项目文件结构，确认所有文件存在 * 验证 package.json、vite.config.ts、tsconfig.json 配置正确 * 确认所有组件文件已创建 ### ================================================================================ \[2024-12-19\] 修复网页空白问题 问题：用户直接打开 index.html 显示空白 根本原因： 这是一个现代前端项目，使用： * Vite 作为构建工具 * TypeScript 需要编译 * ES6 模块系统 * React JSX 需要转换 直接打开 HTML 文件无法工作，因为： 1. 浏览器无法直接执行 TypeScript (.tsx) 2. 无法处理 import/export 模块系统 3. 无法处理 JSX 语法 4. 需要 Vite 开发服务器进行实时编译和热更新 正确启动方式： 1. 安装依赖：npm install 2. 启动开发服务器：npm run dev 3. 在浏览器中访问显示的地址（通常是 http://localhost:5173） 操作： * 创建 START_HERE.txt 文件，提供清晰的启动说明 * 更新日志文件记录此操作 * 确保所有配置文件正确 * 修复 CubeVisualizer.tsx 中的代码错误： * 添加缺失的 useRef 导入 * 移除未使用的 isProcessingRef 引用 ### ================================================================================ \[2024-12-19\] 代码修复 修复 CubeVisualizer.tsx 组件中的错误： 问题1：缺少 useRef 导入 * 第17行使用了 useRef 但未导入 * 修复：在导入语句中添加 useRef 问题2：未定义的 isProcessingRef * 第103和116行引用了不存在的 isProcessingRef * 修复：移除这些引用，使用 isAnimating 状态即可 操作： * 修复 src/components/CubeVisualizer.tsx * 验证代码无 lint 错误 * 更新日志记录 ================================================================================ ### ![在这里插入图片描述](https://i-blog.csdnimg.cn/direct/47a873e7ef9b433eaba0571ccf383065.png) ![在这里插入图片描述](https://i-blog.csdnimg.cn/direct/2a1cc0a979f542ab85b3a2a96d0b6f8a.png) \[2024-12-19\] 修复代码逻辑和实现真正的3D旋转 用户反馈问题： 1. 输入 RUR'U' 后执行半天没停下来 2. 需要真正的3D层旋转动画，而不是刷新颜色 问题分析： 1. useEffect的依赖问题导致重复执行 2. setTimeout没有正确清理 3. 当前实现只是更新颜色，没有真正的3D旋转 解决方案： 1. 修复useEffect清理逻辑，正确管理setTimeout 2. 实现真正的3D旋转动画系统： * 创建RotatingLayer组件处理单层旋转 * 使用useFrame实现平滑动画 * 按层分组方块，旋转整个层 * 动画完成后更新cubeState 实现细节： * RotatingLayer组件使用useFrame逐帧更新旋转角度 * 根据move类型确定旋转轴（X/Y/Z）和角度 * 正确识别需要旋转的方块（按层分组） * 使用递归executeMove函数逐步执行公式 * 每个move等待600ms（动画500ms + 缓冲100ms） 操作： * 完全重写 CubeVisualizer.tsx * 实现RotatingLayer组件 * 修复动画同步问题 * 更新日志记录 ### ================================================================================ \[2024-12-19\] 创建用户启动文档 用户要求：创建详细的启动步骤文档，放在_User文件夹中 操作： * 创建 _User 文件夹 * 创建 _User/启动项目步骤.txt 文件 * 包含完整的启动步骤： * 第一步：检查环境（Node.js安装） * 第二步：打开项目文件夹 * 第三步：安装项目依赖 * 第四步：启动开发服务器 * 第五步：在浏览器中打开网站 * 第六步：使用网站 * 停止服务器方法 * 常见问题解决 * 快速命令参考 * 项目结构说明 * 更新日志记录此操作 ================================================================================ ![在这里插入图片描述](https://i-blog.csdnimg.cn/direct/2b5028b2840f4568b6929809f925be11.png) 先睡了，晚安