写在前面：为什么又写了一篇环境搭建？
说实话，我本来想跳过这一篇的。毕竟"React + Vite 搭建项目"这种教程，掘金上一搜少说几百篇，我再写一篇有什么意思？
但当我真的动手开始做这个开源项目的时候，我发现了一个问题------网上的教程全都过时了。
React 19 出了，API 变了；Vite 8 发布了，配置改了；Tailwind CSS v4 也来了，连 PostCSS 的玩法都换了。再看那些教程，还在用 React 18、Vite 4、Tailwind v3，复制粘贴过去全是报错。
好，既然没人写新的，那我自己写。顺便吐槽一下这些"又新又坑"的变化。
一、创建项目：Vite 8 终于不那么"快"了
先说明一下环境要求：
- Node.js 20+（别问为什么，问就是 Vite 8 要求）
- pnpm / npm / yarn 任选（推荐 pnpm，后面你装依赖就知道为什么了）
1.1 创建命令
bash
pnpm create vite@latest my-project --template react执行完这个命令，你会看到：
erlang
Scaffolding project in my-project...
Done.然后 cd 进去，安装依赖：
bash
cd my-project
pnpm install吐槽时间：
Vite 官方说自己是"极速构建工具"，但 pnpm install 这一步该慢还是慢。尤其在大陆网络环境下，node_modules 永远在卡 90%。不过相比 Webpack，确实算快了------只是别信那些"秒装"的宣传，那是演示项目。
1.2 升级到 React 19
Vite 的 React 模板默认还是 React 18.3，我们需要手动升级到 19。
打开 package.json，找到 react 和 react-dom，改成：
json
"dependencies": {
"react": "^19.0.0",
"react-dom": "^19.0.0"
}然后重新安装：
bash
pnpm installReact 19 的坑 ：ReactDOM.render 没了，现在用 createRoot。但好消息是 Vite 模板已经帮你改好了，不用手动改。如果你是从老项目升级，准备好改几十个文件吧。
二、Tailwind CSS v4 配置：这可能是最折腾的一步
Tailwind CSS v4 最大的变化是：不再需要 tailwind.config.js 了（终于做了个对的决定）。
但坏消息是：PostCSS 配置方式变了，和 v3 完全不兼容。
2.1 安装依赖
bash
pnpm add tailwindcss@next @tailwindcss/postcss postcss autoprefixer注意 @next 标签，因为 v4 目前还是 pre-release 版本（没错，写这篇教程时它还在 beta，等你们看到可能已经正式发布了，但配置逻辑应该不变）。
2.2 配置 PostCSS
删除原来的 postcss.config.js（如果存在），新建 postcss.config.mjs（注意后缀，Vite 8 对 ESM 更友好）：
javascript
// postcss.config.mjs
export default {
plugins: {
'@tailwindcss/postcss': {},
autoprefixer: {},
},
}遇到的坑 ：如果你用 .js 后缀且 package.json 里 "type": "module"，可能会报 require is not defined。直接改成 .mjs 就能解决。
2.3 创建 Tailwind 入口文件
新建 src/index.css（如果已存在就清空），写入：
css
@import 'tailwindcss';然后确保你的 src/main.jsx 引入了这个 CSS：
jsx
import './index.css'
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import App from './App.jsx'
createRoot(document.getElementById('root')).render(
<StrictMode>
<App />
</StrictMode>,
)2.4 验证配置
在 App.jsx 里写一段测试代码：
jsx
function App() {
return (
<div className="min-h-screen bg-gradient-to-r from-blue-500 to-purple-600 flex items-center justify-center">
<h1 className="text-white text-4xl font-bold">
React 19 + Vite 8 + Tailwind v4 🚀
</h1>
</div>
)
}
export default App运行 pnpm dev，如果能看到一个蓝紫色渐变背景的大标题，恭喜你，配置成功了。
如果没成功------别慌，检查一下：
postcss.config.mjs有没有写对index.css里有没有@import 'tailwindcss'- 浏览器控制台有没有报错（大概率是 PostCSS 插件没找到，重新
pnpm install试试）
三、目录结构设计：拒绝"全塞进 src"
很多新手项目喜欢把所有东西堆在 src/ 下，然后 components、pages、utils、hooks 全平铺。项目一超过 50 个文件就直接炸了。
我建议用这个结构（也是本系列后续文章会采用的）：
csharp
my-project/
├── public/ # 静态资源，直接复制不进打包
│ └── favicon.svg
├── src/
│ ├── assets/ # 需要打包的静态资源（图片、字体等）
│ │ └── logo.svg
│ ├── components/ # 通用组件
│ │ ├── Button/
│ │ │ ├── Button.jsx
│ │ │ └── Button.module.css # 如果不用 Tailwind 的样式
│ │ └── index.js # 统一导出
│ ├── features/ # 按功能模块划分的代码
│ │ └── auth/
│ │ ├── components/
│ │ ├── hooks/
│ │ └── api.js
│ ├── hooks/ # 全局复用 hooks
│ ├── utils/ # 工具函数
│ ├── pages/ # 路由页面
│ ├── styles/ # 全局样式
│ │ └── index.css
│ ├── App.jsx
│ ├── main.jsx
│ └── vite-env.d.ts # 如果用了 TypeScript
├── .gitignore
├── index.html
├── package.json
├── pnpm-lock.yaml
├── postcss.config.mjs
├── vite.config.js
└── README.md为什么要这样设计？
features/比pages/好用：页面相关的所有代码（组件、hooks、API 调用）都放在一起，改功能不用跨文件夹找文件。这是借鉴了"Feature-based architecture"的思路。components/只放真正全局通用的组件，比如Button、Modal、Input。如果一个组件只在一个页面用，就放在对应features里。别怕移动文件，IDE 重构功能很好用。
四、ESLint 配置：你跟我的 eslint.config.js 一样恶心对吧？
ESLint 从 v9 开始默认使用 flat config（eslint.config.js），不再支持 .eslintrc。Vite 8 创建的模板默认也是新的 flat config。
但问题来了：React 19 有一些新的 lint 规则，而社区插件还没完全跟上。
4.1 安装依赖
bash
pnpm add -D eslint eslint-plugin-react eslint-plugin-react-hooks @eslint/js4.2 配置 eslint.config.js
javascript
// eslint.config.js
import js from '@eslint/js'
import pluginReact from 'eslint-plugin-react'
import pluginReactHooks from 'eslint-plugin-react-hooks'
export default [
js.configs.recommended,
{
files: ['**/*.{js,jsx}'],
plugins: {
react: pluginReact,
'react-hooks': pluginReactHooks,
},
languageOptions: {
parserOptions: {
ecmaFeatures: {
jsx: true,
},
ecmaVersion: 'latest',
sourceType: 'module',
},
globals: {
// 浏览器环境全局变量
document: 'readonly',
window: 'readonly',
console: 'readonly',
},
},
rules: {
// React 19 新变化：不再需要 import React 了
'react/react-in-jsx-scope': 'off',
// 但 hooks 规则还是要开着
'react-hooks/rules-of-hooks': 'error',
'react-hooks/exhaustive-deps': 'warn',
// 其他推荐规则
'react/prop-types': 'off', // 如果你用了 TypeScript 就关掉
'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
},
settings: {
react: {
version: '19.0',
},
},
},
]吐槽 ：这个 flat config 从 v9 推出到现在，官方文档还是写得像天书。我到现在都记不住 languageOptions 和 parserOptions 的层级关系，每次都得翻示例。要不是为了兼容 Vite 8，我真想锁死 ESLint v8。
4.3 添加 npm script
json
"scripts": {
"lint": "eslint src --ext .js,.jsx",
"lint:fix": "eslint src --ext .js,.jsx --fix"
}运行 pnpm lint，看有没有报错。
五、Git 初始化 + GitHub 仓库：别把 node_modules 传上去了
5.1 初始化 Git
bash
git init
git add .
git commit -m "chore: initial project setup with React 19 + Vite 8 + Tailwind v4"5.2 检查 .gitignore
Vite 模板生成的 .gitignore 已经包含：
bash
node_modules
dist
dist-ssr
*.local千万别删 ，尤其是 node_modules。我见过有人不小心上传了 node_modules，然后仓库直接膨胀到几百 MB，拉代码要十分钟。
5.3 创建 GitHub 仓库并推送
- 去 GitHub 新建一个仓库（不要勾选"Add a README file"）
- 复制仓库地址，比如
git@github.com:你的用户名/项目名.git - 关联远程仓库并推送：
bash
git remote add origin git@github.com:你的用户名/项目名.git
git branch -M main
git push -u origin mainSSH vs HTTPS：推荐用 SSH 方式（上面的地址是 SSH 格式），省得每次 push 输密码。如果还没配置 SSH key，参考 GitHub 官方文档，五分钟搞定。
六、运行验证
最后跑一下开发服务器：
bash
pnpm dev打开 http://localhost:5173，你应该能看到那个渐变的欢迎页面。
再试一下构建：
bash
pnpm build成功后会生成 dist/ 目录，里面是优化后的生产代码。
总结：环境搭完了，然后呢？
恭喜你，现在你已经有了一个能跑起来的 React 19 + Vite 8 + Tailwind CSS v4 项目。
但这才只是开始。接下来我们还要：
- 配置路由（React Router v7 配合 React 19 也有坑）
- 状态管理（Zustand vs Redux Toolkit，我选前者）
- 封装 API 请求（用 React Query 还是 SWR？）
- 添加 UI 组件库（shadcn/ui 还是 Ant Design？）
这些都是第 3 篇及以后的内容。
最后说一句：如果你严格按照步骤来还是遇到报错，八成是依赖版本的问题。React 19 和 Tailwind v4 都还很新，生态工具没完全跟上。可以尝试降级到 React 18 + Tailwind v3 等稳定版，或者去 GitHub Issues 里翻一翻------大概率有人在三天前遇到了同样的问题，而且还没人回答。
祝你好运，也祝我好运。我们下一篇再见。
下一篇预告：React Router v7 配置 + 代码分割实战（顺便吐槽 v6 到 v7 的 breaking changes）