环境搭建 #

一、环境要求 #

1.1 Node.js 版本 #

Astro 需要 Node.js 环境，版本要求如下：

Astro 版本	Node.js 最低版本
Astro 4.x	Node.js 18.14.1+
Astro 3.x	Node.js 18.14.1+
Astro 2.x	Node.js 16.12.0+

1.2 检查当前环境 #

bash

# 检查 Node.js 版本
node -v

# 检查 npm 版本
npm -v

# 检查 pnpm 版本（如果已安装）
pnpm -v

二、安装 Node.js #

2.1 macOS 安装 #

方式一：使用 Homebrew（推荐）

bash

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

# 安装 Node.js
brew install node

# 验证安装
node -v
npm -v

方式二：使用 nvm（Node Version Manager）

bash

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

# 重新加载终端配置
source ~/.zshrc

# 安装最新 LTS 版本
nvm install --lts

# 使用 LTS 版本
nvm use --lts

2.2 Windows 安装 #

方式一：使用官方安装包

访问 Node.js 官网
下载 LTS 版本安装包
运行安装程序，按提示完成安装

方式二：使用 nvm-windows

powershell

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

# 安装 Node.js
nvm install 20

# 使用指定版本
nvm use 20

2.3 Linux 安装 #

Ubuntu/Debian：

bash

# 使用 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node -v
npm -v

CentOS/RHEL：

bash

# 使用 NodeSource 仓库
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

# 验证安装
node -v
npm -v

三、包管理器选择 #

3.1 npm #

Node.js 默认包管理器：

bash

# 查看版本
npm -v

# 初始化项目
npm init

# 安装依赖
npm install

# 添加依赖
npm install package-name

# 全局安装
npm install -g package-name

3.2 pnpm（推荐） #

高效、节省磁盘空间的包管理器：

bash

# 安装 pnpm
npm install -g pnpm

# 查看版本
pnpm -v

# 安装依赖
pnpm install

# 添加依赖
pnpm add package-name

# 全局安装
pnpm add -g package-name

pnpm 优势：

特性	说明
节省空间	使用硬链接，减少磁盘占用
安装快速	并行安装，速度更快
依赖严格	避免幽灵依赖
Monorepo	原生支持 monorepo

3.3 yarn #

Facebook 开发的包管理器：

bash

# 安装 yarn
npm install -g yarn

# 查看版本
yarn -v

# 安装依赖
yarn

# 添加依赖
yarn add package-name

# 全局安装
yarn global add package-name

四、创建 Astro 项目 #

4.1 使用创建向导（推荐） #

bash

# 使用 npm
npm create astro@latest

# 使用 pnpm
pnpm create astro@latest

# 使用 yarn
yarn create astro

4.2 创建向导选项 #

运行创建命令后，会出现交互式选项：

text

╭─────╮  Houston:
│ ◠ ◡ ◠  Let's build something great!
╰─────╯

 astro   v4.x.x Launch sequence initiated.

✔ Where would you like to create your new project? › my-project
✔ How would you like to start your new project? › Include sample files
✔ Install dependencies? › Yes
✔ Initialize a new git repository? › Yes
✔ How would you like to setup TypeScript? › Strict

4.3 项目模板选择 #

Astro 提供多种启动模板：

模板	说明
Empty	空项目，最小配置
Blog	博客模板
Docs	文档站模板
Portfolio	作品集模板
Minimal	最小示例

使用模板创建：

bash

# 使用博客模板
npm create astro@latest -- --template blog

# 使用文档模板
npm create astro@latest -- --template docs

# 使用最小模板
npm create astro@latest -- --template minimal

4.4 从 GitHub 模板创建 #

bash

# 从 GitHub 仓库创建
npm create astro@latest -- --template github-user/repo-name

# 示例：使用官方博客模板
npm create astro@latest -- --template withastro/astro/tree/main/examples/blog

五、编辑器配置 #

5.1 VS Code（推荐） #

安装 Astro 扩展：

打开 VS Code
按 Cmd+Shift+X（macOS）或 Ctrl+Shift+X（Windows）
搜索 “Astro”
安装官方 Astro 扩展

扩展功能：

语法高亮
代码补全
错误提示
格式化支持
预览功能

5.2 VS Code 配置 #

在项目根目录创建 .vscode/settings.json：

json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "astro-build.astro-vscode",
  "astro.typescript.enabled": true,
  "[astro]": {
    "editor.defaultFormatter": "astro-build.astro-vscode"
  }
}

5.3 其他编辑器 #

WebStorm / IntelliJ IDEA：

安装 Astro 插件
启用 TypeScript 支持

Sublime Text：

安装 Package Control
安装 Astro 语法包

Vim / Neovim：

使用 LSP 配置
安装 astro-language-server

六、开发服务器 #

6.1 启动开发服务器 #

bash

# 进入项目目录
cd my-project

# 启动开发服务器
npm run dev

# 或使用 pnpm
pnpm dev

6.2 开发服务器选项 #

bash

# 指定端口
npm run dev -- --port 3001

# 指定主机
npm run dev -- --host 0.0.0.0

# 打开浏览器
npm run dev -- --open

6.3 访问开发服务器 #

text

  🚀  astro  v4.x.x started in 123ms

  ┃ Local    http://localhost:4321/
  ┃ Network  http://192.168.1.100:4321/

七、项目脚本 #

7.1 package.json 脚本 #

json

{
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro check && astro build",
    "preview": "astro preview",
    "astro": "astro"
  }
}

7.2 脚本说明 #

脚本	命令	说明
dev	`npm run dev`	启动开发服务器
start	`npm start`	同 dev
build	`npm run build`	构建生产版本
preview	`npm run preview`	预览构建结果

八、常见问题 #

8.1 Node 版本不兼容 #

bash

# 使用 nvm 切换版本
nvm install 20
nvm use 20

# 或使用 nvm-windows（Windows）
nvm install 20
nvm use 20

8.2 依赖安装失败 #

bash

# 清除缓存
npm cache clean --force

# 删除 node_modules 重新安装
rm -rf node_modules package-lock.json
npm install

# 或使用 pnpm
rm -rf node_modules pnpm-lock.yaml
pnpm install

8.3 端口被占用 #

bash

# 指定其他端口
npm run dev -- --port 3001

# macOS/Linux 查找占用端口的进程
lsof -i :4321

# 终止进程
kill -9 <PID>

九、总结 #

环境搭建步骤总结：

text

┌─────────────────────────────────────────────────────┐
│                 Astro 环境搭建步骤                   │
├─────────────────────────────────────────────────────┤
│                                                     │
│  1. 安装 Node.js (18.14.1+)                        │
│     └── 使用 Homebrew / nvm / 官方安装包            │
│                                                     │
│  2. 选择包管理器                                    │
│     └── npm / pnpm (推荐) / yarn                   │
│                                                     │
│  3. 创建 Astro 项目                                 │
│     └── npm create astro@latest                    │
│                                                     │
│  4. 配置编辑器                                      │
│     └── VS Code + Astro 扩展                       │
│                                                     │
│  5. 启动开发服务器                                  │
│     └── npm run dev                                │
│                                                     │
└─────────────────────────────────────────────────────┘

下一步，让我们了解项目结构，熟悉 Astro 项目的目录组织！