写在前面这方面，为什么又写了一篇环境搭建？

实际来说，我本来想跳过这一篇的。毕竟“React + Vite 搭建项目”这种教程。掘金上一搜少说几百篇，我再写一篇有什么意思？

但当我真的动手开始做这个开源项目的时候，我发现了一个问题——网上的教程全都过时了。

React 已经出了新版本，API 变了；Vite 发布了新版本，配置改了；Tailwind CSS v4 也来了连 PostCSS 的玩法都换了。再看那些教程，还在用旧版 React、Vite、Tailwind v3。复制粘贴过去全是报错，

好，既然没人写新的，那我自己写。顺便吐槽一下这些“又新又坑”的变化。

一、创建项目：Vite 终于不那么“快”了

先说明一下环境要求：

• Node.js +
• pnpm / npm / yarn 任选

创建命令

pnpm create vite@latest my-project --template react

执行完这个命令。你会看到：

Scaffolding project in my-project...
Done.

接下来 cd 进去，安装依赖：

cd my-project
pnpm install

吐槽时间：

Vite 官方说自己是“极速建立工具”，但 pnpm install 这一步该慢还是慢。说起来，在大陆网络环境下node_modules 永远在卡 %。相比 Webpack，确实算快了——只是别信那些“秒装”的宣传，那是演示项目。

到最新 React

Vite 的 React 模板默认还是老版本，需要手动升级到最新。

打开 package.json找到 "react" 和 "react-dom"改成：

"dependencies": {
"react": "^18.2.0","react-dom": "^18.2.0"
}

接下来重新安装：

pnpm install

React 的坑：ReactDOM.render 没了现在用 createRoot. 好消息是 Vite 模板已经帮你改好了不用手动改。如果你是从老项目升级，准备好改几十个文件吧。

二、Tailwind CSS v4 配置：这可能是最折腾的一步

关键痛点：Tailwind v4 把传统的 tailwind.config.js 扔进垃圾桶。却把 PostCSS 的配置方式彻底翻天覆地，让很多人踩坑。

安装依赖

pnpm add tailwindcss@next @tailwindcss/postcss postcss autoprefixer

*注意* @next 标签，因为 v4 目前还是 pre‑release。等你看到正式版时只要把标签去掉即可。

配置 PostCSS

删除原来的 postcss.config.js新建 postcss.config.mjs

// postcss.config.mjs
export default {
plugins: {
'@tailwindcss/postcss': {}。autoprefixer: {}
}
}

Pain point：If you keep .js extension while having "type":"module" in your package.json,you’ll hit “require is not defined”. Switching to .mjs solves it instantly.

Create Tailwind entry file

/* src/index.css */
@import 'tailwindcss';

确保在入口文件里引入它：

import './index.css';import { StrictMode } from 'react';说起来，import { createRoot } from 'react-dom/client';import App from './App.jsx';
createRoot).render(



);

验证配置是否成功

function App {
return (


React + Vite + Tailwind v4 🚀


);}
export default App;

A run of `pnpm dev` d should display a blue‑purple gradient with a big title.

• If you don’t see it。check:
  1. The syntax of .mjs` config file.
  2. The presence of @import 'tailwindcss'.
  3. The browser console for “PostCSS plugin not found” errors – re‑run Pnpm install​.This step alone solves more than half of “my Tailwind isn’t working” tickets on GitHub.

     三、目录结构设计：拒绝“全塞进 src”

     Pain point: 许多新人把所有文件平铺在 src 下一旦项目突破十几个文件，就会出现找不到组件、方法冲突甚至编译慢的问题。

     I recommend a feature‑based layout :

     
     my-project/
     ├── public/ # 静态资源。不参与打包
     │ └── favicon.svg
     ├── src/
     │ ├── assets/ # 打包的图片、字体等
     │ │ └── logo.svg
     │ ├── components/ # 真正全局复用的 UI
     │ │ ├── Button/
     │ │ │ ├── Button.jsx
     │ │ │ └── Button.module.css
     │ │ └── index.js # 导出统一入口
     │ ├── features/ # 按业务划分的模块
     │ │ └── auth/
     │ │ ├── components/
     │ │ ├── hooks/
     │ │ └── api.js
     │ ├── hooks/ # 跨模块共享的自定义 Hook
     │ ├── utils/ # 工具函数库
     │ ├── pages/ # 路由页面
     │ ├── styles/ # 全局 CSS / Tailwind 自定义层级
     │ │ └── 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/` vs `pages/`: 把页面相关的所有代码放一起，让功能迭代不必跨目录搜索。按理说，
     • `components/`: 仅存放真正全局可复用的 UI。如 Button、Modal。页面专属的组件直接归属对应 feature 文件夹即可。
     • The structure scales gracefully—add a new feature folder and you’re done.

       四、ESLint 配置：你跟我的 eslint.config.js 一样恶心对吧？怎么说呢，

       Pain point: ESLint 从 v9 起默认使用 flat config。而大多数社区插件文档仍停留在旧版格式，使得新人常常报错找不到规则。

        pnpm add -D eslint eslint-plugin-react eslint-plugin-react-hooks @eslint/js
       

       配置 eslint.config.js

        // eslint.config.js
       import js from '@eslint/js';import pluginReact from 'eslint-plugin-react';import pluginReactHooks from 'eslint-plugin-react-hooks';export default,plugins: {
       react这方面，pluginReact,'react-hooks': pluginReactHooks,},languageOptions: {
       parserOptions: {
       ecmaFeatures: { jsx: true },ecmaVersion: 'latest',sourceType: 'module',},globals: {
       document: 'readonly',window: 'readonly',console: 'readonly',},}。rules: {
       // React 新变化：不再需要 import React
       'react/react-in-jsx-scope': 'off',// Hooks 必须开启
       'react-hooks/rules-of-hooks': 'error','react-hooks/exhaustive-deps': 'warn',// 如果使用 TypeScript 可以关闭 prop-types 检查
       'react/prop-types': 'off',// 常规建议
       'no-unused-vars':,},settings: { react: { version: '' } },// 自动检测
       },];

       吐槽 ： 这个 flat config 从 v9 推出到现在官方文档仍像天书。我每次都要翻示例才能记住 languageOptions vs parserOptions 层级关系 。如果不是为了兼容 Vite，我真想锁死 ESLint v8。

       添加 npm script

        "scripts": {
       "lint"这方面，"eslint src --ext .js,.jsx","lint:fix": "eslint src --ext .js。.jsx --fix"
       } 

       Run pnpm lint​ to see if any rule violations appear.

       五、Git 初始化 + GitHub 仓库：别把 node_modules 传上去了

       初始化 Git

        git init
       git add .
       git commit -m "chore: initial project setup with React + Vite + Tailwind v4"
       

       bash node_modules dist dist-ssr *.local

       node_modules。一次有人误推上去导致仓库体积暴涨到几百 MB，克隆耗时十分钟以上。

       <\="" ="" github="" li\>="" 去="" 复制仓库地址，例如="" 新建仓库="">:。<\/li\> <\="" li\>="" ol="" 关联远程并推送：="">

       \
       git remote add origin :<你的用户名>/<项目名>.git\
       git branch -M main\
       git push -u origin main\
       <\/cоde><\/prе>
       >
       >
       
       
       
       
       bash
       pnpm dev
       
       
       打开 http://localhost:应能看到渐变背景的大标题。
       
       再执行一次建立：
       
       bash
       pnpm build
       
       
       成功后会生成 dist/ 文件夹，其中存放的是生产环境已调整好的代码。