web 项目本地启动行为规范

Bolt
78 阅读4分钟

给岁月以文明，而不是给文明以岁月。

-- 『三体』

项目应当让新人入手更简单, 而不是艰难的熟悉了之后觉得这样也还能接受.

团队现状

入手成本高

  • 新人不知道如何启动项目

  • 执行启动命令后一堆报错

  • 项目启动起来之后页面上报错

对新同学的要求

前端必备基础知识
开发习惯培养

  • 拿到新项目先看 README.md

  • 根据 lock 文件选择对应的 npm / pnpm / yarn, 防止不同的 lock 文件提交到 git 仓库

  • 查看 package.json 中的 scripts 有哪些

新建项目脚手架的要求

足够简单的 README

  • README.md 文件内容应该足够简单, 不适合描述整个项目的技术方案

  • 最应该写的内容是如何启动项目

  • 项目的技术方案应该使用飞书或其他成体系的文档工具, 并将入口链接放在README.md

设计简单好用的启动项目方案

参考:

  • 将 .env 文件提交到 git 仓库, 在不切换环境的情况下, 使用默认环境启动, 默认环境应当为 prd 环境

  • 自动化脚本应当与 env 解耦

脚手架范例

足够简单的 README
# xxx-vite

技术文档: xxx

## 启动

`pnpm i` 安装依赖, 并 __切换环境__ 后执行 `pnpm run dev`

按提示配置 `/etc/hosts`, 并 __登录相关环境__

## 切换环境

1. `pnpm run env:list` - 查看所有可选环境模板
2. `pnpm run env:use <env>` - 切换要选择的模版
    - 如: `pnpm run env:use boe` 表示使用 boe.env 作为模版生成 `.env.local`
3. 可以手动修改基于模板编辑生成的 `.env.local` 文件
启动命令友好提示
  • hosts 没有正确配置的情况下会有报错提示
  • 提示的访问域名直接替换成 hosts 配置的 local 域名
  • 引导登录, 而不需要手动获取 cookie
通过 node 代理实现接口与页面不跨域

如 www.xxx-pre.cn/xxx/web 请求的接口域名也是 www.xxx-pre.cn 是不跨域的

本地开发时, 接口还是应该访问页面相同域名, 借助 vite 内置的 http-proxy 代理到实际远程接口.

作为开发标准, create-react-app / vue-cli / vite / parcel 等集成工具, 均会内置http-proxy.

项目脚手架应尽可能的不额外使用 charles 或 nginx 启动代理, 用来减少新人开发成本.

通过 hosts 配置 local 域名获取 cookie 登录信息

如本地启动 local.xxx-pre.cn , 可以访问 www.xxx-pre.cn/approval/we… 进行登录

本地接口代理到 www.xxx-pre.cn, 请求时 local.xxx-pre.cn 页面会携带 .xxx-pre.cn 域的 cookie

切换环境工具与开发流程解耦

基于命令切换 .env.local (.env.local 不提交到 git 仓库):

  • yarn env:list - 列出所有可选 env 文件

  • yarn env:use <name> - 切换到 <name>.env

可选的 env 文件

模版可以存在 git 仓库的 envs 文件夹里, 命令仅仅是复制和重命名.

也可以有在线配置中心, 通过命令生成本地 local 文件

env:list 命令

#!/usr/bin/env sh

cd envs
pwd

echo ''
echo '== env 可选列表:'
ls -1 | grep .env

echo ''
echo '== run `yarn env:use <name>` 切换到 [name].env'
echo '== 如: `yarn env:use boe` 切换到 boe.env'
echo ''

env:use 命令

#!/usr/bin/env sh

cd envs
pwd

echo ''
echo '== env 可选列表:'
ls -1 | grep .env

echo ''
echo "== 您选择了 $1.env"
cat $1.env > ../.env.local
echo "== 已输出到 .env.local"
番外: 默认启动的页面一定不要报错

以 xxx-web 举例

启动后页面一直 loading, 是因为项目没有首页

  • 一些子项目的组合, 各自有启动路由

  • 详情页面需要根据登录账号传入可用的详情 id

如果没有默认首页, 应当创建一个开发者引导页, 用来列出当前项目有哪些页面.

如果详情页访问需要登录绑定的详情 id 信息, 可以在引导页打接口获取一些可用的详情.

总结

pnpm i 安装依赖并切换环境后, 执行 pnpm run dev

按提示配置 /etc/hosts , 并登录相应环境账号.

  • 不需要借助 charles 等三方代理

  • 不需要手动抓 cookie 写入到本地

  • hosts 修改首次配置, 永久生效

  • 不切换环境的情况下, 使用 .env 默认启动 prd 环境

  • 切换环境后, 仍然可以手动修改 local 配置

avatar
文章
阅读
粉丝