头图

在不断发展的 Web 开发领域,对于任何希望提高性能和可维护性的开发人员来说,掌握高效的工具和流程都至关重要。对于许多希望构建现代单页 React 应用程序的人来说,Vite 已成为 Create React App (CRA) 的自然继任者。在本综合指南中,我们将逐步介绍将您的项目从 CRA 迁移到 Vite 的步骤,重点是实用性和易用性。

距离 Vite 推出已经有4年时间,Vite 5.0 版本在23年11月也正式发布,使用 Rollup 4使得构建性能的幅提升,同时还有一些新的选项可以改善开发服务器性能,在刚发布的时候就了解了它的底层原理和实现方式,但是因为种种原因并没有敢在正式环境使用它,比如正式环境与开发环境表现不一致,对一些边缘问题处理存在问题等等,通过 issue 也能反应出来。但是最近工作中的项目越积越大导致开发环境代码热更新越来越慢使得我不得不再次考虑把原项目从 CRA 中迁移到 VIte 做一次大胆的尝试,接下来就看看如何进行迁移吧:

了解从 CRA 到 Vite 的转变

在深入探讨实际步骤之前,让我们先了解一下为什么这次迁移可以彻底改变您的开发工作流程。CRA 一直是引导 React 应用的首选解决方案,无需配置麻烦。然而,Vite 提供了更快的开发体验,具有热模块替换 (HMR) 和开箱即用的高效构建优化等功能。Vite 更精简、更现代的方法可以显著提高开发和生产的性能。

逐步迁移:开启你的 Vite 之路

安装 Vite

迁移从安装 Vite 和 React 相关库作为开发依赖项开始。在项目的根目录中运行以下命令:

yarn add vite @vitejs/plugin-react --save-dev

卸载 create-react-app 的依赖:

yarn remove react-scripts

修改 package.json 文件,使用以下新的脚本:

调整 package.json 文件的“scripts”部分以使用 Vite 的命令:

"scripts": {
  "dev": "vite",
  "build": "vite build",
  "serve": "vite preview"
}

将文件扩展名重命名为 .jsx 或 .tsx

Vite 通过显式扩展名来区分文件。对于 JSX 文件,你应该将它们从 .js 重命名为 .jsx。如果你使用的是 TypeScript,同样适用,从 .ts 重命名为 .tsx

mv src/App.js src/App.jsx
mv src/index.js src/index.jsx

创建 vite.config.js 文件

vite.config.js在项目的根目录中创建一个 vite.config.js 文件并补充配置信息以反映你的构建偏好。

touch vite.config.js

这是一个基本配置:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig(() => {
  return {
    build: {
      outDir: 'dist',
    },
    plugins: [react()],
  };
});

还可以包含其他配置来满足特定的项目需求,例如设置路径别名:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig(() => {
  return {
    build: {
      outDir: 'dist',
    },
    plugins: [react()],
    resolve: {
      alias: {
        '@': path.resolve(__dirname, './src'),
        '@common': path.resolve(__dirname, './src/common'),
        '@pages': path.resolve(__dirname, './src/pages')
      }
    }  
  };
});

修改 index.html 文件

把原来 public 目录下的 index.html 移动到项目根目录下,并在文件中找到所有的 %PUBLIC_URL% 然后删除。

- <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
+ <link rel="manifest" href="/manifest.json" />

html 引入 src/index.js

<body>
  <noscript>You need to enable JavaScript to run this app.</noscript>
  <div id="root"></div>
  <script type="module" src="/src/index.tsx"></script>
</body>

额外的配置细节

配置 Vite TS 类型支持

{
  "compilerOptions": {
    "types": ["vite/client"],
  }
}

兼容 TailwindCSS 在 vite 项目中使用

根目录下创建 postcss.config.js 文件:

module.exports = {
  plugins: [require('tailwindcss'), require('autoprefixer')]
}

安装 polyfill

很多依赖会使用 node 中的模块 api导致项目在启动后会报类似的错误:

Cannot read properties of undefined (reading 'prototype')

使用 polyfill 抹平这些不同环境下的差异:

yarn add vite-plugin-node-polyfills

vite.config.js 中配置这个插件:

import { defineConfig } from 'vite'
import { nodePolyfills } from 'vite-plugin-node-polyfills'

export default defineConfig(() => {
  return {
    // 省略其他配置
    plugins: [react(), nodePolyfills()],
  }
})

配置环境变量

如果之前项目中使用 dotenv 来实现环境变量的基本可以废弃了,Vite 本身支持的环境变量就已经足够应对基本的需求了,使用 mode 指定环境从而加载对应的env 配置文件获取对应的变量:

"scripts": {
    "dev": "vite",
    "build:prod": "vite build --mode production",
    "build:stage": "vite build --mode staging",
    "serve": "vite preview"
  },
  1. yarn dev 对应开发环境,它会去加载 .env.development 文件中的信息;
  2. yarn build:stage 对应预发环境,它会去加载 .env.staging文件中的信息;
  3. yarn build:prod 对应正式环境,它会去加载 .env.production文件中的信息;

注意:env 中的变量如果需要客户端可访问,变量名必须以 VITE_ 开头,类似与 nextjs 中 NEXT_PUBLIC_:

# .env.development
VITE_APP_ENV=dev

使用 import.meta.env.xxx 获取对应的变量值:

const env = import.meta.env.VITE_APP_ENV
console.log(env) // dev

在之前的项目中,你很有可能是这样获取环境变量的:

const env = process.env.REACT_APP_ENV

并且有很多第三方依赖包中也可能用到这种语法,但是在 Vite 直接写这个会报错,为了兼容第三方依赖包不报错,在 vite.config.js 中补充 define 配置:

import { defineConfig } from 'vite'

export default defineConfig(() => {
  return {
    // 省略其他配置
    define: {
      'process.env': {}
    }
  }
})

配置端口和接口请求代理

vite.config.js 中使用 server 配置:

import { defineConfig } from 'vite'

export default defineConfig(() => {
  return {
    // 省略其他配置
    server: {
      port: 8080,
      proxy: {
        '/api': {
          target: 'https://app-dev.blocksec.com',
          changeOrigin: true,
          secure: false
        }
      }
    }
  }
})

配置 less 预解析

import { defineConfig } from 'vite'

export default defineConfig(() => {
  return {
    // 省略其他配置
    css: {
      preprocessorOptions: {
        less: {
          math: 'always',
          relativeUrls: true,
          javascriptEnabled: true
        }
      }
    }
  }
})

完成迁移

完成上述步骤后,您就可以启动新的基于 Vite 的 React 应用了。只需运行:

yarn dev

总结

从 CRA 过渡到 Vite 可以为你带来更快的构建速度、简化的开发体验和更高的性能。正如上面所概述的,迁移过程很容易,但可能需要进行调整以适应你的项目的定制化需求,请密切关注官方 Vite 文档


MangoGoing
774 声望1.2k 粉丝

开源项目:详见个人详情