企业官网建设流程全解析

vue-pure-admin 快速上手：4 步跑通 Vue3 后台项目，Docker 一键部署到服务器

【免费下载链接】vue-pure-admin全面ESM+Vue3+Vite+Element-Plus+TypeScript编写的一款后台管理系统（兼容移动端）项目地址: https://gitcode.com/GitHub_Trending/vu/vue-pure-admin

vue-pure-admin 是一套基于 Vue 3.5 + Vite 8 + Element Plus + TypeScript 的 ESM 后台管理系统模板，把登录认证、菜单权限、多布局、国际化这些中后台必备能力做成了开箱即用的样子。读完本文，你能在本地几分钟内看到登录页，改掉 3 处关键配置，并用一条 Docker 命令把它部署到服务器。

项目定位与适用场景：vue-pure-admin 适合谁

先看技术栈底数（均来自仓库 README.md 与 package.json）：

• 适合谁：需要从零搭一个中后台、但不想自己写登录/权限/布局骨架的开发者或前端小组。
• 特色：内置 mock 接口，不依赖后端就能完整体验登录、角色权限（admin/common 两套角色）。
• 与同类方案差异：纯 ESM + 精简依赖，没有历史包袱；布局、主题、多标签页等配置集中在少数环境变量和 store 里，改造成本比大而全的框架低。
• 不适合：只需要一个静态官网，或者团队只熟 Vue 2 的场景。

4 步跑通项目：vue-pure-admin 本地启动登录页

第 1 步：克隆代码

git clone https://gitcode.com/GitHub_Trending/vu/vue-pure-admin cd vue-pure-admin

目录里能看到package.json、pnpm-lock.yaml、.env三个文件就算成功。

第 2 步：确认环境版本

node -v && pnpm -v

Node 必须 >= 22.22.1（仓库.nvmrc建议 24.19.0），pnpm 必须 >= 11。版本不达标会直接安装失败，先升级 Node 再继续。

第 3 步：安装依赖

pnpm install

项目用preinstall: npx only-allow pnpm锁死了包管理器，用 npm 或 yarn 会立刻报错。装完出现node_modules且无红色报错即成功。

第 4 步：启动开发服务器

pnpm dev

浏览器访问http://localhost:8848（注意是 8848 而不是 80），出现登录页后输入默认账号admin、密码admin123，进入首页看到仪表盘即全链路跑通。

跑通后必改的几个关键配置：3 处最影响你

1. 端口与部署路径：.env与.env.production

.env里的VITE_PORT = 8848决定本地访问地址，8848 被占用时改成VITE_PORT = 9999再重启即可。生产打包路径看.env.production的VITE_PUBLIC_PATH = /，如果你的站点挂在/admin子目录，这里要同步改成/admin/，否则静态资源全部 404。

2. 路由模式与压缩：.env.production

VITE_ROUTER_HISTORY = "hash" VITE_COMPRESSION = "none"

默认hash模式刷新不白屏、Nginx 零配置，新手建议保留；切"h5"后需要在 Nginx 加try_files $uri $uri/ /index.html;。把VITE_COMPRESSION改成"brotli"可给产物生成 .br 压缩文件，配合 Nginx 的brotli_static on能明显减小传输体积——这是仓库自带的性能开关，不用额外装插件。

3. 跨域代理：vite.config.ts

server.proxy: {}目前为空。本地联调真实后端时，在这里加一条规则（如"/api": { target: "http://后端地址", changeOrigin: true }），前端请求就能免跨域直达后端。接完真实后端后，记得去掉mock/目录里对应的假接口，避免两边打架。

从本地到服务器：vue-pure-admin Docker 最稳部署方式

仓库自带多阶段 Dockerfile：node:20-alpine负责构建（已内置 npmmirror 镜像源加速），产物拷进nginx:stable-alpine对外服务，.dockerignore已排除node_modules等无关文件，构建上下文很干净。

1. 构建镜像

docker build -t vue-pure-admin .

构建成功会输出Successfully built开头的镜像 ID。

2. 启动容器

docker run -d -p 8080:80 --name pure-admin vue-pure-admin

把容器 80 端口映射到主机 8080，-d让它在后台常驻。

3. 验证部署

curl -I http://localhost:8080

返回HTTP/1.1 200即 Nginx 已就绪；浏览器打开http://localhost:8080，用admin/admin123登录成功，部署完成。🚀

高频坑位速查：vue-pure-admin 安装部署 5 个常见坑

• 现象：pnpm install 立刻报 ERR_PNPM 或 preinstall 失败。原因：项目强制只允许 pnpm。修复：统一改用 pnpm，别混用 npm/yarn。
• 现象：pnpm dev 起来了但页面空白。原因：默认端口是 8848，很多人按 5173 访问。修复：改访问地址，或在.env里改VITE_PORT。
• 现象：Node 低版本安装报 ERR_OSSL 或语法错误。原因：engines 要求 Node >= 22.22.1。修复：升级到 Node 22+（建议对齐.nvmrc的 24.19.0）再装依赖。
• 现象：线上刷新子页面白屏。原因：把路由切成了h5模式但 Nginx 没配回退。修复：Nginx 加try_files $uri $uri/ /index.html;，或改回hash。
• 现象：docker build 卡在依赖下载。原因：走了海外源。修复：Dockerfile 已配置 npmmirror，确认没改错npm config set registry那行即可，必要时检查宿主机网络。

从克隆、启动、改配置到 Docker 上线，本文已经把 vue-pure-admin 的完整链路走了一遍。想继续深入，可以阅读 README.md 了解全部内置能力，或从src/router/目录开始动手定制自己的菜单与页面。

【免费下载链接】vue-pure-admin全面ESM+Vue3+Vite+Element-Plus+TypeScript编写的一款后台管理系统（兼容移动端）项目地址: https://gitcode.com/GitHub_Trending/vu/vue-pure-admin