第02章-环境搭建与快速开始

第二章：环境搭建与快速开始

2.1 环境要求

在开始使用或开发Astral3D之前，需要准备好相应的开发环境。本节将详细介绍系统要求和必备软件。

2.1.1 操作系统要求

Astral3D支持以下操作系统：

操作系统 版本要求 备注
Windows Windows 10/11 推荐64位系统
macOS 10.15+ (Catalina及以上) 支持Intel和Apple Silicon
Linux Ubuntu 18.04+等主流发行版 推荐使用LTS版本

2.1.2 浏览器要求

运行Astral3D编辑器需要支持WebGL的现代浏览器：

浏览器 最低版本 推荐版本 备注
Google Chrome 90+ 最新版 推荐
Mozilla Firefox 90+ 最新版 良好支持
Microsoft Edge 90+ 最新版 Chromium内核
Safari 14+ 最新版 macOS优先

注意：Internet Explorer不被支持，请使用Edge或其他现代浏览器。

2.1.3 开发环境要求

进行Astral3D二次开发需要以下工具：

工具 版本要求 说明
Node.js ≥ 18.x（推荐23.11.x+） JavaScript运行时环境
pnpm ≥ 8.x 推荐的包管理器
Git ≥ 2.30 版本控制工具
VS Code 最新版 推荐的代码编辑器

2.1.4 硬件建议

为获得最佳开发和运行体验，建议配置：

配置项 最低要求 推荐配置
CPU 双核2GHz 四核3GHz+
内存 8GB 16GB+
显卡 支持WebGL2 独立显卡
硬盘 10GB可用空间 SSD
网络 稳定连接 宽带连接

2.2 安装Node.js

Node.js是Astral3D开发的基础，推荐使用版本管理工具来安装和管理Node.js版本。

2.2.1 Windows系统安装

方法一：直接安装（推荐新手）

  1. 访问Node.js官网：https://nodejs.org/
  2. 下载LTS（长期支持）版本的安装包
  3. 运行安装程序，按照向导完成安装
  4. 安装过程中勾选"Add to PATH"选项

方法二：使用nvm-windows

# 1. 下载nvm-windows安装包
# 访问：https://github.com/coreybutler/nvm-windows/releases

# 2. 运行安装程序

# 3. 重启终端后安装Node.js
nvm install 23.11.0
nvm use 23.11.0

# 4. 验证安装
node --version
npm --version

2.2.2 macOS系统安装

方法一：使用Homebrew

# 安装Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装Node.js
brew install node

# 验证安装
node --version
npm --version

方法二：使用nvm（推荐）

# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重新加载shell配置
source ~/.bashrc  # 或 source ~/.zshrc

# 安装Node.js
nvm install 23.11.0
nvm use 23.11.0
nvm alias default 23.11.0

# 验证安装
node --version
npm --version

2.2.3 Linux系统安装

Ubuntu/Debian系统：

# 使用nvm安装（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重新加载配置
source ~/.bashrc

# 安装Node.js
nvm install 23.11.0
nvm use 23.11.0

# 验证
node --version
npm --version

使用NodeSource仓库：

# 添加NodeSource仓库
curl -fsSL https://deb.nodesource.com/setup_23.x | sudo -E bash -

# 安装Node.js
sudo apt-get install -y nodejs

# 验证
node --version
npm --version

2.3 安装pnpm

Astral3D项目使用pnpm作为包管理器，相比npm具有更快的安装速度和更好的依赖管理。

2.3.1 安装pnpm

方法一：使用npm安装（推荐）

npm install -g pnpm

# 验证安装
pnpm --version

方法二：使用corepack（Node.js 16.13+内置）

# 启用corepack
corepack enable

# 安装pnpm
corepack prepare pnpm@latest --activate

# 验证
pnpm --version

方法三：独立安装

# Linux/macOS
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Windows PowerShell
iwr https://get.pnpm.io/install.ps1 -useb | iex

2.3.2 pnpm基础配置

# 设置淘宝镜像源（国内用户推荐）
pnpm config set registry https://registry.npmmirror.com

# 查看当前配置
pnpm config list

# 设置全局存储位置（可选）
pnpm config set store-dir ~/.pnpm-store

2.4 安装Git

Git是克隆和管理Astral3D源代码的必要工具。

2.4.1 Windows安装

  1. 访问Git官网：https://git-scm.com/download/win
  2. 下载并运行安装程序
  3. 安装过程中建议选择以下选项：
    • Default editor: 选择您喜欢的编辑器（VS Code推荐）
    • PATH environment: Git from the command line and also from 3rd-party software
    • Line ending conversions: Checkout Windows-style, commit Unix-style line endings

2.4.2 macOS安装

# 方法一：使用Homebrew
brew install git

# 方法二：使用Xcode命令行工具
xcode-select --install

2.4.3 Linux安装

# Ubuntu/Debian
sudo apt update
sudo apt install git

# Fedora
sudo dnf install git

# Arch Linux
sudo pacman -S git

2.4.4 Git基础配置

# 配置用户信息
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# 验证配置
git config --list

# 验证安装
git --version

2.5 安装VS Code

VS Code是进行Astral3D开发的推荐编辑器，提供了优秀的TypeScript支持和丰富的插件生态。

2.5.1 下载安装

  1. 访问VS Code官网：https://code.visualstudio.com/
  2. 下载对应系统的安装包
  3. 运行安装程序完成安装

2.5.2 推荐插件

为获得最佳的Astral3D开发体验，建议安装以下VS Code插件：

插件名称 用途
Vue - Official Vue 3官方支持
TypeScript Vue Plugin (Volar) Vue TypeScript支持
ESLint 代码规范检查
Prettier 代码格式化
GitLens Git增强功能
Path Intellisense 路径智能补全
Auto Import 自动导入
Error Lens 错误高亮显示

安装插件命令行方式：

code --install-extension Vue.volar
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension eamodio.gitlens

2.5.3 VS Code配置建议

创建或编辑.vscode/settings.json：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.preferences.importModuleSpecifier": "relative",
  "vue.codeActions.enabled": false,
  "[vue]": {
    "editor.defaultFormatter": "Vue.volar"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

2.6 克隆项目

环境准备就绪后，可以开始克隆Astral3D项目。

2.6.1 克隆主仓库

# 克隆项目（使用HTTPS）
git clone https://github.com/mlt131220/Astral3D.git

# 或使用SSH（需配置SSH密钥）
git clone git@github.com:mlt131220/Astral3D.git

# 进入项目目录
cd Astral3D

2.6.2 查看项目结构

# 查看目录结构
ls -la

# 主要目录说明
# packages/         - 源码包（SDK和编辑器）
# public/           - 静态资源
# examples/         - 示例项目
# docs/             - 文档

2.6.3 切换分支

# 查看所有分支
git branch -a

# 切换到开发分支（如需最新功能）
git checkout develop

# 查看当前分支
git branch

2.7 安装依赖

2.7.1 安装项目依赖

# 确保在项目根目录
cd Astral3D

# 使用pnpm安装依赖
pnpm install

安装过程说明：

  • 首次安装可能需要5-15分钟，取决于网络速度
  • pnpm会创建.pnpm缓存目录复用依赖
  • 安装完成后会生成node_modules目录

2.7.2 处理安装问题

问题一：网络超时

# 设置淘宝镜像
pnpm config set registry https://registry.npmmirror.com

# 重新安装
pnpm install

问题二：依赖冲突

# 清理缓存
pnpm store prune

# 删除node_modules重新安装
rm -rf node_modules
pnpm install

问题三：权限错误

# Linux/macOS - 避免使用sudo安装npm包
# 修改npm默认目录权限或使用nvm

# Windows - 以管理员身份运行终端

2.7.3 验证安装

# 查看已安装的依赖
pnpm list

# 查看特定包版本
pnpm list three
pnpm list vue

2.8 构建和运行

2.8.1 构建SDK

在运行编辑器之前，需要先构建SDK：

# 构建SDK
pnpm run sdk:build

# 构建成功后会在packages/sdk/dist生成构建产物

2.8.2 启动开发服务器

# 启动编辑器开发服务器
pnpm run editor:dev

成功启动后的输出：

  VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:3000/
  ➜  Network: http://192.168.x.x:3000/
  ➜  press h + enter to show help

打开浏览器访问 http://localhost:3000 即可看到Astral3D编辑器界面。

2.8.3 生产构建

# 构建生产版本
pnpm run editor:build

# 构建完成后，产物位于packages/editor/dist目录

2.8.4 预览生产构建

# 预览生产构建
pnpm run editor:preview

2.9 项目结构概览

2.9.1 根目录结构

Astral3D/
├── packages/                # 源码包
│   ├── sdk/                 # SDK核心库（@astral3d/engine）
│   └── editor/              # 编辑器应用
├── public/                  # 静态资源
├── examples/                # 示例项目
├── docs/                    # 文档
├── scripts/                 # 构建脚本
├── .github/                 # GitHub配置
├── package.json             # 项目配置
├── pnpm-workspace.yaml      # pnpm工作区配置
├── tsconfig.json            # TypeScript配置
├── vite.config.ts           # Vite配置
└── README.md                # 项目说明

2.9.2 SDK包结构

packages/sdk/
├── src/
│   ├── core/                # 核心模块
│   │   ├── Viewer.ts        # 主视图类
│   │   ├── Scene.ts         # 场景管理
│   │   └── Camera.ts        # 相机控制
│   ├── loader/              # 加载器模块
│   │   ├── GLTFLoader.ts    # GLTF加载器
│   │   ├── OBJLoader.ts     # OBJ加载器
│   │   └── FBXLoader.ts     # FBX加载器
│   ├── controls/            # 控制器
│   ├── effects/             # 特效
│   ├── plugins/             # 插件
│   └── signals/             # 事件系统
├── dist/                    # 构建产物
├── package.json
└── tsconfig.json

2.9.3 编辑器包结构

packages/editor/
├── src/
│   ├── components/          # Vue组件
│   │   ├── toolbar/         # 工具栏组件
│   │   ├── sidebar/         # 侧边栏组件
│   │   ├── viewport/        # 视口组件
│   │   └── panels/          # 面板组件
│   ├── views/               # 视图页面
│   ├── stores/              # Pinia状态管理
│   ├── plugins/             # 编辑器插件
│   ├── utils/               # 工具函数
│   ├── App.vue              # 应用入口
│   └── main.ts              # 主入口
├── public/                  # 静态资源
├── index.html
├── package.json
└── vite.config.ts

2.10 常用命令汇总

2.10.1 开发命令

# 安装依赖
pnpm install

# 构建SDK
pnpm run sdk:build

# 启动开发服务器
pnpm run editor:dev

# 生产构建
pnpm run editor:build

# 预览构建产物
pnpm run editor:preview

# 代码检查
pnpm run lint

# 代码格式化
pnpm run format

2.10.2 Git常用命令

# 查看状态
git status

# 拉取更新
git pull

# 切换分支
git checkout <branch-name>

# 创建新分支
git checkout -b <new-branch-name>

# 提交更改
git add .
git commit -m "提交信息"

# 推送到远程
git push origin <branch-name>

2.10.3 pnpm常用命令

# 添加依赖
pnpm add <package-name>

# 添加开发依赖
pnpm add -D <package-name>

# 移除依赖
pnpm remove <package-name>

# 更新依赖
pnpm update

# 查看依赖树
pnpm list --depth=1

2.11 常见问题解决

2.11.1 启动失败

问题：端口被占用

# 查找占用端口的进程
# Windows
netstat -ano | findstr :3000

# Linux/macOS
lsof -i :3000

# 终止进程或更换端口
# 在vite.config.ts中修改server.port

问题：模块找不到

# 清理并重新安装
rm -rf node_modules
rm -rf packages/*/node_modules
pnpm install
pnpm run sdk:build

2.11.2 构建失败

问题：TypeScript错误

# 检查TypeScript配置
pnpm run type-check

# 查看详细错误信息
pnpm run sdk:build --verbose

问题：内存不足

# 增加Node.js内存限制
export NODE_OPTIONS="--max-old-space-size=8192"
pnpm run editor:build

2.11.3 性能问题

问题：开发服务器响应慢

# 检查是否有大量文件监听
# 排除node_modules等目录

# 使用SSD存储项目文件
# 增加系统内存

2.12 本章小结

本章详细介绍了Astral3D的环境搭建过程，主要内容包括：

  1. 环境要求：操作系统、浏览器、开发工具的版本要求
  2. Node.js安装：多平台安装方法和版本管理
  3. pnpm安装：包管理器的安装和配置
  4. Git安装：版本控制工具的安装和基础配置
  5. VS Code配置：推荐插件和开发设置
  6. 项目克隆：获取源代码的方法
  7. 依赖安装：处理依赖安装和常见问题
  8. 构建运行：SDK构建和开发服务器启动
  9. 项目结构：源码目录结构介绍
  10. 常见问题：环境搭建中的问题解决

完成本章的学习后，读者应该能够：

  • 独立搭建Astral3D开发环境
  • 成功运行Astral3D编辑器
  • 理解项目的基本结构
  • 解决常见的环境问题

下一章预告：第三章将深入介绍Astral3D的核心架构和技术栈，包括Viewer核心类、事件系统、模块化设计等内容，帮助读者理解Astral3D的内部工作原理。

posted @ 2026-01-10 13:17  我才是银古  阅读(22)  评论(0)    收藏  举报