Remix环境搭建 #

一、环境要求 #

在开始之前，请确保你的开发环境满足以下要求：

要求	版本	说明
Node.js	18.0+	推荐使用 LTS 版本
npm/yarn/pnpm	最新版	包管理器
编辑器	-	推荐 VS Code

二、安装Node.js #

2.1 macOS安装 #

方法一：使用 Homebrew（推荐）

bash

brew install node@20

方法二：使用 nvm（版本管理器）

bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.zshrc
nvm install 20
nvm use 20
nvm alias default 20

2.2 Windows安装 #

方法一：官网安装包

访问 Node.js官网
下载 LTS 版本安装包
运行安装程序

方法二：使用 winget

bash

winget install OpenJS.NodeJS.LTS

方法三：使用 nvm-windows

bash

nvm install 20
nvm use 20

2.3 Linux安装 #

Ubuntu/Debian：

bash

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

CentOS/RHEL：

bash

curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

使用 nvm：

bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

三、验证安装 #

bash

node --version
npm --version

预期输出：

text

v20.11.0
10.2.4

四、创建Remix项目 #

4.1 使用创建向导 #

Remix 提供了交互式的项目创建工具：

bash

npx create-remix@latest

按照提示选择：

text

? Where would you like to create your app? my-remix-app
? What type of app do you want to create? Just the basics
? Where do you want to deploy? Choose Remix App Server if you're unsure; it's easy to change deployment targets.
? TypeScript or JavaScript? TypeScript
? Do you want me to run `npm install`? Yes

4.2 使用模板创建 #

可以直接指定模板：

bash

npx create-remix@latest my-app --template remix-run/remix/templates/remix

常用模板：

模板	说明
remix	基础模板
remix-javascript	JavaScript版本
remix-run/indie-stack	全栈模板（含数据库）
remix-run/blues-stack	全栈模板（含测试）

4.3 使用不同的包管理器 #

bash

npx create-remix@latest my-app --npm
npx create-remix@latest my-app --yarn
npx create-remix@latest my-app --pnpm

五、项目结构 #

创建完成后，项目结构如下：

text

my-remix-app/
├── app/
│   ├── components/        # 组件目录
│   ├── routes/            # 路由文件
│   │   ├── _index.tsx     # 首页
│   │   └── about.tsx      # /about 页面
│   ├── entry.client.tsx   # 客户端入口
│   ├── entry.server.tsx   # 服务端入口
│   └── root.tsx           # 根组件
├── public/                # 静态资源
│   └── favicon.ico
├── package.json
├── remix.config.js        # Remix配置（v1）
├── vite.config.ts         # Vite配置（v2）
└── tsconfig.json          # TypeScript配置

六、启动开发服务器 #

进入项目目录并启动：

bash

cd my-remix-app
npm run dev

打开浏览器访问 http://localhost:5173

七、VS Code配置 #

7.1 推荐扩展 #

创建 .vscode/extensions.json：

json

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "ms-vscode.vscode-typescript-next"
  ]
}

7.2 工作区设置 #

创建 .vscode/settings.json：

json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

八、常用脚本命令 #

在 package.json 中定义的脚本：

json

{
  "scripts": {
    "dev": "remix vite:dev",
    "build": "remix vite:build",
    "start": "remix-serve ./build/server/index.js",
    "typecheck": "tsc"
  }
}

命令	说明
npm run dev	启动开发服务器
npm run build	构建生产版本
npm run start	启动生产服务器
npm run typecheck	TypeScript类型检查

九、安装常用依赖 #

9.1 UI框架 #

bash

npm install tailwindcss postcss autoprefixer
npx tailwindcss init -p

9.2 数据库 #

bash

npm install prisma @prisma/client
npx prisma init

9.3 表单验证 #

bash

npm install zod

9.4 测试工具 #

bash

npm install -D vitest @testing-library/react @testing-library/jest-dom

十、常见问题 #

10.1 端口被占用 #

bash

npm run dev -- --port 3000

10.2 Node版本过低 #

确保 Node.js 版本 >= 18：

bash

node --version

如果版本过低，请升级 Node.js。

10.3 依赖安装失败 #

尝试清除缓存：

bash

rm -rf node_modules package-lock.json
npm install

10.4 TypeScript错误 #

确保安装了类型定义：

bash

npm install -D @types/react @types/react-dom

十一、开发工具推荐 #

11.1 浏览器扩展 #

React DevTools：React调试工具
Remix DevTools：Remix专用调试工具

11.2 命令行工具 #

npm-run-all：并行运行脚本
cross-env：跨平台环境变量

bash

npm install -D npm-run-all cross-env

十二、总结 #

本章我们学习了：

环境要求：Node.js 18+
创建项目：使用 create-remix 命令
项目结构：了解各目录的作用
开发工具：VS Code配置和推荐扩展

安装完成后，让我们进入下一章，创建第一个 Remix 应用！