Vue3Template

Vite + Vue3 + TypeScript + Element Plus + Pinia 项目模板

技术栈：node.js + TypeScript + Vite + Vue 3 + Vue Router 4 + Axios + Pinia + Element Plus

node.js: 作者本人使用18.19.0。

pnpm: 作者本人使用8.12.1。

其他细节可见：package.json

许可（License）

本项目使用MIT LICENSE许可证发布。

MIT License: mit-license.org

配置文件

配置文件通常为.env开头的文件。例如开发模式会读取.env.development文件，生产模式会读取.env.production文件。 当然，读取文件的后缀是根据pacckage.json中的指令决定的。具体更详细的说明可见后文。

配置项如下：

VITE_HASH # 对于资源文件（例如图片）在build的时候，是否在文件名上添加哈希。具体作用见后文。
VITE_VISUALIZE # 是否在构建时生成构建分析报告（HTML交互式报告）。具体作用见后文。
VITE_API_BASE_URL # API请求前缀。具体作用见后文。
VITE_PROXY_TARGET # 代理目标。具体作用见后文。

读取配置文件的说明

{
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc && vite build",
    "build:beta": "vue-tsc && vite build --mode beta",
    "preview": "vite preview"
  }
}

在程序dev中，调用vite指令会读取.env.development文件，而程序build则会调用vite build指令且读取.env.production文件。 你也可以通过--mode参数指定需要读取的文件，例如vite build --mode beta会读取.env.beta文件。

资源文件名添加哈希的说明（VITE_HASH）

资源文件名添加哈希，可以保证每次项目重新构建时，资源文件名称不同，可以防止浏览器缓存问题（浏览器缓存旧版本的资源文件而不是使用新构建时的资源文件）。 在开发模式时建议设置为false，因为这样可以方便调试。在生产模式时建议设置为true，因为这样可以保证资源文件的唯一性。

构建时生成HTML交互式报告（VITE_VISUALIZE）

启用visualizer 构建时插件。改插件通常用于 JavaScript 应用的打包分析。它可以帮助开发者可视化地理解最终打包产物的结构、大小分布以及依赖关系。 他会在构建目录下生成报告的交互页面（例如：./dist/report），内部浏览完毕后建议删除该目录再上传到生产环境，当然你也可以保留以供你的用户浏览。

API请求前缀（VITE_API_BASE_URL）

该配置需要与后端同步（请见后文）

此处不考请求跨域问题，默认为不跨域

例如你的API请求前缀为https://api.example.com，那么你可以在.env文件中设置VITE_API_BASE_URL = https://api.example.com。

当然，如果你的API的路径都具有一个固定的前缀（例如：/api/v1），那么你可以射中VITE_API_BASE_URL = https://api.example.com/api/v1， 这样当系统请求/user/info的时候就会请求https://api.example.com/api/v1/user/info。

这样做还要一种好处，例如你后端简体的api是/user/info，正常来说前端应该请求https://api.example.com/user/info，其中/user/info会单独写在项目的api文件中， 并且和VITE_API_BASE_URL拼接生成最终请求地址（https://api.example.com/user/info）。 但是当你后端使用Nginx（或其他技术）做了反向代理，将/api/v1代理到了/，那么前端就应该请求https://api.example.com/api/v1/user/info， 此时只需要修改VITE_API_BASE_URL的值为（https://api.example.com/api/v1）即可，而不需要修改项目中的api文件中的user/info。

与后端同步配置

该配置在一般情况下应该与后端配置文件的http.baseapi保持一致。注意，http.baseapi的默认值是/api，当http.baseapi为空时也会使用默认值。

若使用了Nginx（或其他技术）的反向代理，则请确保VITE_API_BASE_URL的值与反向代理的值保持一致。即访问VITE_API_BASE_URL的值时，会被代理到后端的http.baseapi。

代理目标（VITE_PROXY_TARGET）

仅用于测试环境

开启后，将会将/api开头的请求转发到VITE_PROXY_TARGET上。 例如，请求axios.get('/api/user/info')则反向代理到VITE_PROXY_TARGET + '/api/user/info'上。

这么做的一个主要原因是解决跨域问题。前端在测试时通常是localhost:8080（端口号可能不同），后端可能则不在此地址上（尽管也可能在localhost上，但端口号不同，则仍然可能造成跨域）。 因此需要vite进行一个反向代理。

生产环境下不需要此功能，通常使用Nginx（或其他技术）解决问题，让后端和前端在一起，即同一个IP或域名，同一个端口号（例如常见的443和80）。

运行和构建

下文使用npm为例，作者实际上使用的是pnpm。

当然，你可以尝试使用yarn，作者在此之前并未尝试过。

运行前，你需要安装一些node模块。请执行：

npm install

运行

开发运行模式请执行（配置文件为.env.development，你应该对其进行修改为你的配置）：

npm run dev

你将在命令行看到服务启动的提示，以及监听地址。 访问监听地址，你就可以看到前端了。

通过此方式启动的开发运行模式具有热模块替换（HMR）、快速重新加载等特性，适合开发调试。

构建

对于生产环境构建，请执行（配置文件为.env.production，你应该对其进行修改为你的配置）：

npm run build

构建的结果将在.\dist-production下。

构建完成后，可以通过执行preview命令，来启动一个简易服务器（类似于Nginx）来部署构建结果：

npm run preview

这并不是开发运行模式，而是把经过上述方式构建生成的文件（.\dist-production）模拟生产环境进行预览。 在运行此命令之前，你应该先进行构建，并生成.\dist-production目录。

鸣谢

感谢Jetbrains AI Assistant（中国大陆版）为本项目提供了AI（人工智能）技术支持。

感谢Vite、Vue、Vue Router、Vuex、Axios、Element Plus等开源项目为本项目提供了技术支持。

感谢Github平台为本项目提供了代码托管服务。

特别鸣谢本项目所有贡献者和贡献团体对本项目的支持，你可以从PR记录、Commit记录中查看到他们的名字和贡献。