【山竹记账前端-vue】1.搭建前端项目.md

大纲链接 §

[toc]

1. 使用 oh-my-env 开发环境 ⇧

快速启动开发环境 ⇧

• 下载 oh-my-env-1
• 使用 VSCode 打开目录
  • 预装 Docker Desktop 加速镜像已配置
  • 预装插件 Dev Container
  • 已开启 wsl 等
  • 详见 搭建Docker开发环境
• Reopen in Container 等加载完毕，可关闭当前终端窗口
• 另外打开终端 默认使用 zsh
• 使用 nvm install 22 最新版
  • 单独安装 pnpm：
  • 首先 npm install --global corepack@latest
  • 然后 corepack enable
  • 最后 corepack prepare pnpm@11.27.0 --activate
• 工作目录 ~/repos 在这个目录中创建项目目录
• 根目录 ~ 即 /root
  • 放置 .ssh 目录
  • 放置 .bashrc 文件
  • 放置 .gitconfig 文件

快速配置开发环境 ⇧

锁死 npm 版本号

• 运行 npm config set save-prefix='' 去除 ^

配置 ssh，快速使用 github 项目

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 现代 SSH 密钥的首选推荐
ssh-keygen -t ed25519 -C "your_email@example.com"
cat ~/.ssh/id_ed25519.pub
# 将显示的文本输入github的ssh秘钥配置
# 添加host列表
ssh-keyscan github.com >> /root/.ssh/known_hosts
# 验证
ssh -T git@github.com
############################################################
############################################################
# 传统 SSH 密钥
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
cat ~/.ssh/id_rsa.pub
# 其他步骤一致

• 参考：请问两种ssh生成方式有什么区别，哪一种更好，还有其他方式吗

配置 git，快速使用 github 项目

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

git config --global user.name xmasuhai
git config --global user.email xmasuhai@163.com
# 设置 git push 的默认行为
git config --global push.default simple
# 禁止对包含中文等非 ASCII 字符的文件路径进行引号转义
git config --global core.quotepath false
# 将默认的文本编辑程序设置为 VS Code
git config --global core.editor "code --wait"
# 控制换行符的自动转换
git config --global core.autocrlf input
# 设置通过 git init 创建的新仓库的默认第一个主分支名称为 master
git config --global init.defaultBranch master
# 禁用忽略大小写
git config --global core.ignorecase false
# 启用长文件名称
git config --system core.longpaths true
# 查看配置
git config --list
git config --global --list

搭建前端框架 ⇧

• 前端技术栈 Vite 8 + Vue 3 + Typescript 7(TSX) + VueRouter 5 + Pinia
• 开发环境：全程使用 我的开发环境 oh-my-env-1
  • node@19.9.0 (npm v8.19.2) （使用nvm use system开启）
  • pnpm@6.32.3（推荐代替npm 和 yarn）
  • 使用淘宝 npm 源加速 npm config set registry=https://registry.npmmirror.com
  • 不推荐npm@8.19.2（备用）、yarn@1.22.22（备用）

后续升级记录（20260920）

• node@22.23.2 (npm@10.9.8)
  • nvm alias system 22.23.2
  • nvm alias default system
• pnpm@11.27.0

创建前端项目 ⇧

• 运行 cd ~/repos
• 运行 nvm use system 或者升级到稳定版 nvm use 22
• 创建项目，以下命令二选一：
  • pnpm create vite@8.3.0 mangosteen-fe-0 --template vue-ts
  • pnpm create vite@8.3.0 根据脚手架提示选择选项
  • 项目名称：mangosteen-fe-0
  • 框架：Vue
  • 框架变体-Vue官方启动器：Official Vue Starter
  • 是否使用Vite 8：Yes
  • 是否使用 TypeScript 语法 Yes
  • 选择要包含的功能
    • JSX 支持
    • Router（单页面应用开发）
    • Pinia（状态管理）
    • Vitest（单元测试）
    • 端到端测试
    • Linter（错误预防）
    • Prettier（代码格式化）
  • 端到端测试框架：Cypress
  • 试验特性：
    • 使用 Oxfmt 替代 Prettier
    • 使用 typescript-native-bridge（tsgo）替代 TypeScript
  • 包管理器：pnpm
• 按照提示执行后续命令
  • 推荐将 cd mangosteen-fe-0 改为 code mangosteen-fe-0 使用 VSCode 打开

1
2
3
4
5

code mangosteen-fe-0
   pnpm install
   pnpm format
   pnpm dev
git init && git add -A && git commit -m "initial commit"

安装完毕

1
2
3
4
5
6

pnpm i
#...
Packages are hard linked from the content-addressable store to the virtual store.
  Content-addressable store is at: ~/.pnpm-store/v11
  Virtual store is at:             node_modules/.pnpm
Progress: resolved 624, reused 273, downloaded 284, added 557, done

• 虚拟软链接地址 node_modules/.pnpm
• 实际安装地址 .pnpm-store/v11
• 可以节省磁盘空间

添加版本固定配置（文件） ⇧

• pnpm config set save-prefix='' 锁定版本；还需要在 package.json 中手动去除 ^，全局替换
  • 手动维护依赖版本号更新，也可以安装相关插件提示最新可用lts版本
• .nvmrc 运行命令 echo "22.23.2" >> .nvmrc 锁定版本；
  • 可以写脚本自动切换 node 版本

在 package.json 中锁定 Node.js 版本 在 package.json 中添加配置

1
2
3
4
5
6

{
  "engines": {
    "node": ">=22.23.2",
    "pnpm": ">=11.27.0"
  }
}

配置 .npmrc（适用于 npm / pnpm），在项目根目录下创建或编辑 .npmrc 文件，增加以下配置：

• echo 'engine-strict=true' >> .npmrc

  1	engine-strict=true

• 让限制对 npm 生效：默认情况下 engines 限制只对 Yarn/Pnpm 强生效或仅作警告

• 如果使用 npm，需要在项目根目录下创建 .npmrc 文件才会开启严格检查

锁定包管理器

1
2
3
4
5
6

# 确保团队开启了 Corepack
corepack enable
# 本地全局默认配置
corepack prepare pnpm@11.27.0 --activate
# 生成项目配置 packageManager 字段，防止误用其他包管理器
corepack use pnpm@11.27.0

实现硬拦截，配合 preinstall 脚本，防止误用其他包管理器，在 package.json 中添加配置

1
2
3
4
5

{
  "scripts": {
    "preinstall": "npx only-allow pnpm"
  }
}

• 仅可使用 pnpm 安装；运行都可

写到 README.md

• README.md

参考

• 前端项目如何在 package.json 锁定node版本 和 锁定包管理器
• 实现在容器中项目自动切换node版本

2. dev、build 和 preview ⇧

运行开发 pnpm dev

• 开启一个 server 在 Local: http://localhost:5174
  • 这个端口是容器 Linux 的端口
  • VSCode 做了端口自动转发
  • 在宿主机（Windows）中也可访问这个端口

• 注意需要添加 --host 参数，才能转发成功

  1 2 3 4 5 6

  { "scripts": { "dev": "vite --host", "preview": "vite preview --host" } }

运行构建

• 运行 pnpm build
• 遇坑（官方已修复，现无需处理）pnpm build 过程中报第三方打包错误 node_modules/.pnpm/...
  • 处理过程就是报报错信息复制到google/ai中，尝试提示解决方法
  • 在 tsconfig.json 添加 "skipLibCheck": true 到 "compilerOptions" 字段中，可利用 自动补全查看
  • 跳过依赖库代码检查，只需要检查项目代码即可

预览项目

• pnpm preview --host
• 查看dist目录是否能正常运行
• 大约等价于
  • pnpm - http-server
  • http-server -p 4173 dist

3. 修改 build path 部署到 GitHub ⇧

把打包完的代码 dist 部署到 GitHub 或服务器时必须配置 build path

• 配置规则见 vite文档-开发或生产环境服务的公共基础路径
  • 公共基础路径

• 在 vite.config.js 里添加 base: '/' 或 base: '/reponame/' 等

  • '/reponame/' 为github中仓库名称

    1 2 3 4 5 6 7 8

    import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' // https://vitejs.dev/config/ export default defineConfig({ base: '/mangosteen/', plugins: [vue()], })

• 重新打包到 pnpm build

如果仅仅是本地预览，直接 base: '/' 就可以了

• 但是上传 github 会有中间的项目名，base中间写仓库名称即可
• 之后部署章节中会另外说明配属的配置，可用 node 获取环境变量
• 目前暂时用不到

提交完开始部署 git init;git add .;git commit -m 'first commit'

• git相关配置见文章 搭建docker开发环境，配置git/github，创建.ssh 密钥
• 发布到 GitHub

4. 项目目录结构 ⇧

5. Template V.S. TSX ⇧

6. 引入 Vue Router 4 ⇧

7. 引入其他库 ⇧

• pinia
• axios

8. snippet 使用代码片段汇总 ⇧

9. 总结命令汇总 ⇧

参考文章

• 前端代码 github.com/FrankFang/ptmqtd
• 给 JSX 组件也来一份 Vue 式 scoped：jsx-scoped 让样式隔离不再靠自觉
• 我的 Vue 3 + TSX 项目
• react-mangosteen
• mangosteen-src-002

相关文章

• Oh My Docker
• 公共基础路径

• 作者： Joel
• 文章链接：
• 版权声明
• 非自由转载-非商用-非衍生-保持署名