@qse/edu-scripts 0.0.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# 更新日志
+
+## 2.0.0 (2026-03-02)
+
+- breakchange: 使用 rspack 重构

package/README.md

@@ -0,0 +1,107 @@
+# 教育工程化基础框架
+
+svn://192.168.10.168/edu/code/A0.New-system/0A2.front-end-component/edu-scripts/trunk
+
+<Alert>内网里的 @qsb/edu-scripts 已经弃用，请更换成公网的 @qse/edu-scripts </Alert>
+
+## 运行条件
+
+nodejs 版本至少 12+
+
+## 快速体验
+
+执行下面的命令，快速建立一个最小的应用模版，支持 [教育集成 与 独立项目模式](/mode)
+
+```shell
+# npm 安装
+npm create @qse/edu-app@latest
+
+# 或者 yarn 安装
+yarn create @qse/edu-app@latest
+
+# 或者 pnpm 安装
+pnpm create @qse/edu-app@latest
+```
+
+## 安装
+
+<Alert>第一次使用这个框架，请看<Link to="/refactor">老项目接入流程</Link></Alert>
+
+```shell
+npm i @qse/edu-scripts -D
+```
+
+## 用法
+
+`edu-scripts` 可以使用缩写 `edu`，在手写命令行时方便使用
+
+```shell
+# 开发
+edu-scripts start
+# 开发指定端口 默认3000
+edu-scripts start --port 5000
+
+# 打包
+edu-scripts build
+# 打包并分析
+edu-scripts build --analyze
+# 打包并导出 html 文件
+edu-scripts build --output-html
+
+# 部署代码 校端
+edu-scripts deploy -s
+# 部署代码 局端
+edu-scripts deploy -b
+# 部署代码 公文端
+edu-scripts deploy -d
+# 部署代码 校端 + 局端 + 公文端
+edu-scripts deploy -s -b -d
+
+# 生成 override 文件
+edu-scripts generator override
+# 自动生成代码 可使用 npx edu-scripts generator page -h 查看具体效果
+edu-scripts generator page --name <module-name>
+# 生成 tailwind 配置
+edu-scripts generator tailwind
+# 生成 tsconfig 配置
+edu-scripts generator ts
+
+# SVN 提交 dist 到 dist 分支上
+edu-scripts commit-dist
+# SVN 提交 dist 到 dist 分支上，并且删除本地 dist
+edu-scripts commit-dist --rm-local
+```
+
+## ENV 环境变量
+
+| 参数    | 默认值 | 说明         |
+| ------- | ------ | ------------ |
+| PORT    | 3000   | 启动端口     |
+| ANALYZE | false  | 开启打包分析 |
+
+## 自定义配置
+
+```shell
+# 创建 edu-scripts.override.js 文件
+npx edu-scripts g override
+```
+
+具体看[override](/override)
+
+### 自定义 antd 样式
+
+如果不需要，可以跳过
+
+根目录生成 `theme.js` 或 `theme.json`
+
+```js
+module.exports = {
+  '@primary-color': '#99f',
+}
+```
+
+```json
+{
+  "@primary-color": "#99f"
+}
+```

package/app.d.ts

@@ -0,0 +1,73 @@
+declare namespace NodeJS {
+  interface ProcessEnv {
+    readonly NODE_ENV: 'development' | 'production'
+    readonly APP_NAME: string
+    readonly APP_VERSION: string
+  }
+}
+
+declare module '*.avif' {
+  const src: string
+  export default src
+}
+
+declare module '*.bmp' {
+  const src: string
+  export default src
+}
+
+declare module '*.gif' {
+  const src: string
+  export default src
+}
+
+declare module '*.jpg' {
+  const src: string
+  export default src
+}
+
+declare module '*.jpeg' {
+  const src: string
+  export default src
+}
+
+declare module '*.png' {
+  const src: string
+  export default src
+}
+
+declare module '*.webp' {
+  const src: string
+  export default src
+}
+
+declare module '*.md' {
+  const content: string
+  export default content
+}
+
+declare module '*?raw' {
+  const content: string
+  export default content
+}
+
+declare module '*.svg' {
+  import * as React from 'react'
+
+  export const ReactComponent: React.FunctionComponent<
+    React.SVGProps<SVGSVGElement> & { title?: string }
+  >
+
+  const src: string
+  export default src
+}
+
+declare module '*.module.css' {
+  const classes: { readonly [key: string]: string }
+  export default classes
+}
+
+declare module '*.less' {
+  const classes: { readonly [key: string]: string }
+  export default classes
+}

package/babel.config.json

@@ -0,0 +1,3 @@
+{
+  "presets": [["@babel/preset-env", { "targets": { "node": "current" } }]]
+}

package/docs/.vitepress/config.ts

@@ -0,0 +1,35 @@
+import { defineConfig } from 'vitepress'
+import fs from 'fs-extra'
+import path from 'path'
+
+const mds = fs.readdirSync(path.resolve(import.meta.dirname, '..')).filter((s) => s.endsWith('.md'))
+
+const sidebarItems = mds
+  .map((file) => {
+    const md = fs.readFileSync(path.resolve(import.meta.dirname, '..', file), 'utf-8')
+    const title = md.split('\n')[0].match(/#\s+(.+)/)?.[1]
+    if (title) {
+      return { text: title, link: `/${file.replace('.md', '')}` }
+    }
+    return null
+  })
+  .filter((o) => !!o)
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: '@qse/edu-scripts',
+  description: '教育工程化基础框架',
+  base: '/qsxxwapdev/edu-scripts/',
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [],
+
+    sidebar: [
+      { text: '快速开始', link: '/install' },
+      { text: '更新日志', link: '/changelog' },
+      { text: '教程', items: sidebarItems },
+    ],
+
+    socialLinks: [{ icon: 'github', link: 'https://github.com/vuejs/vitepress' }],
+  },
+})

package/docs/changelog.md

@@ -0,0 +1 @@
+<!-- @include: ../CHANGELOG.md -->

package/docs/debug.md

@@ -0,0 +1,17 @@
+# 代码调试
+
+## 使用 `React Developer Tools` 调试
+
+1. 安装 `React Developer Tools` 插件
+2. 打开控制台(F12)
+3. 切换到 `Component` 标签页
+4. 选中需要查看的组件，可以看到 `state/props/hooks` 等信息
+
+## 使用 vscode 调试代码
+
+1. 打开 `JavaScript Debug Terminal` 终端，输入 `npm run start` 命令启动项目。
+
+![](https://p0.meituan.net/dpplatform/78a65449d74d1fbd61cc47e98c419a011041253.gif)
+
+2. 按住 `ctrl/command` 点击 `http://localhost:port` 打开链接
+3. 代码里打断点，网页点击触发断点

package/docs/deploy.md

@@ -0,0 +1,54 @@
+# 部署 v1
+
+项目使用 [@qse/ssh-sftp][1] 部署代码到 v1 环境
+
+## 教育模式
+
+支持 局端/校端/公文 部署。无需额外的配置即可使用
+
+```bash
+# 局端
+npx edu-scripts deploy -b
+
+# 校端
+npx edu-scripts deploy -s
+
+# 公文
+npx edu-scripts deploy -d
+```
+
+## 独立模式
+
+### 默认部署
+
+默认会部署到 `/qsxxwapdev/${package.name}` 路径下
+
+```bash
+npx edu-scripts deploy
+```
+
+### 自定义部署
+
+自定义配置部署路径
+
+```bash
+# 生成配置文件
+npx ssh-sftp init
+```
+
+编辑配置文件
+
+```json
+{
+  "$schema": "http://www.zhidianbao.cn:8088/qsxxwapdev/edu-ssh-sftp/sftprc.schema.json",
+  "preset": {
+    "context": "qsxxwapdev"
+  }
+}
+```
+
+可以使用预设配置，`npx ssh-sftp show-config` 查看最终的配置
+
+其余配置请看 [@qse/ssh-sftp][1]
+
+[1]: http://www.zhidianbao.cn:8088/qsxxwapdev/edu-ssh-sftp/

package/docs/faq.md

@@ -0,0 +1,144 @@
+# 错误处理
+
+## moment 没有 external 掉
+
+全局搜索 `moment/locale/zh-cn`，把这些引入都删除掉即可
+
+## ueditor 提示 css 文件加载不到
+
+移动 `src/ueditor` 到 `public/ueditor`, 导入地址也修改下
+
+例子: `require('../../../public/ueditor/<something>')`
+
+## style 文件报错
+
+```js
+import * as style from './index.less'
+//=> 改成
+import style from './index.less'
+```
+
+## 如果判断是缺少 `alias` 配置，使用 `npx edu-scripts g override` 生成配置文件，并且配置 `alias` 参数
+
+```js
+const { defineConfig } = require('@qse/edu-scripts')
+const path = require('path')
+
+module.exports = defineConfig({
+  alias: {
+    pages: path.resolve('src/pages'),
+  },
+})
+```
+
+## 动态导入 `import`，webpack4 以后 `import` 默认导出改成 `default`
+
+```js
+// 以前写法
+import('lodash/get').then((get) => {
+  get()
+})
+
+// 现在写法
+import('lodash/get').then(({ default: get }) => {
+  get()
+})
+```
+
+## `react` 组件热更新失效
+
+把上面的 `CDN` 加入到首页(index\*.html)中
+
+其中 `process.env.NODE_ENV` 那段代码是关键
+
+热更新需要 react16，请阅读[升级指南](/refactor-react-16)
+
+## 主文件过大，代码分割失效
+
+检查是否有 `require('./chunkfile').default` 这种写法，这会导致代码分割失效，直接打进 main 中
+
+```js
+export default (callback) => {
+  require.ensure([], (require) => {
+    // 错误例子
+    callback(require('./chunkfile').default)
+
+    // 正确写法
+    const mod = require('./chunkfile')
+    callback(mod.default)
+  })
+}
+```
+
+另外，webpack2 开始就不推荐使用 `require.ensure` 做代码分割了。现在可以使用 `import` 方式代码分割
+
+```js
+export default (callback) => {
+  import(/* webpackChunkName: 'chunkfileName' */ './chunkfile').then((mod) => {
+    callback(mod.default)
+  })
+}
+```
+
+## 子工程不能含有 public/static，现已自动删除
+
+子工程不能含有 static 是因为 新建子工程 如果拷贝了主工程代码，那 static 也复制了，打包部署 v1 后可能会覆盖主工程的 static。而且子工程本身就不应该有 static，不可以引入本地外部资源
+
+## qsbAntd is not defiend
+
+子工程项目如果出现这个错误，引入下面的静态资源
+
+```html
+<!-- 确保已经引入 react moment antd -->
+<script src="//www.zhidianbao.cn:8088/qsxxwapdev/edu-scripts/react-dev-preset.js"></script>
+<script src="//www.zhidianbao.cn:8088/qsxxwapdev/edu-scripts/moment2.29.1.js"></script>
+<script src="//www.zhidianbao.cn:8088/qsxxwapdev/edu-scripts/antd3.26.20.js"></script>
+
+<!-- 引入 @qsb/antd -->
+<script src="//www.zhidianbao.cn:8088/qsxxwapdev/edu-scripts/qsb-antd.min.js"></script>
+```
+
+## 钉钉遇到页面打开白屏
+
+这种情况多半是链接中带了 hash，导致页面跳转失败。（复制出来可能是新的链接，但页面其实是老的并未跳转）
+
+将下面两段代码分别加入对应的文件中，必须保证其位置在所有 `script` 最前面
+
+原理： 将 hash 转存至 localStorage，跳转后再取出
+
+```html
+<!-- index.html -->
+<script>
+  ;(function () {
+    var searchString = location.search
+    if (!/(\?|&)S=/.test(searchString)) {
+      var randomHexString = Math.random().toString(32).substring(2)
+      searchString = searchString.substring(1)
+      searchString = '?S=' + randomHexString + (searchString.length > 0 ? '&' + searchString : '')
+    }
+    if (location.hash) {
+      localStorage.setItem('qse:H', location.hash)
+    }
+    var pathnameArr = location.pathname.split('/')
+    var pathname = pathnameArr.slice(0, -1).concat('index1.html').join('/')
+    var __tmp_URL = location.origin + pathname + searchString
+    history.replaceState(null, document.title, __tmp_URL)
+    location.reload()
+  })()
+</script>
+```
+
+```html
+<!-- index1.html -->
+<script>
+  ;(function () {
+    var hash = localStorage.getItem('qse:H')
+    if (hash) {
+      localStorage.removeItem('qse:H')
+      hash = /^#/.test(hash) ? hash : '#' + hash
+      var url = location.origin + location.pathname + location.search + hash
+      history.replaceState(history.state, null, url)
+    }
+  })()
+</script>
+```

package/docs/feat.md

@@ -0,0 +1,167 @@
+# 特性
+
+## svg 模块导出
+
+默认导出 `dataURI`，额外导出 `ReactComponent`
+
+两种使用方式是相同的
+
+```tsx | pure
+import logoURI, { ReactComponent as Logo } from './logo.svg'
+
+export default () => (
+  <>
+    <img src={logoURI} />
+    <Logo />
+  </>
+)
+```
+
+## 复制 public 文件
+
+`edu-scripts build` 会复制 `public` 或 `public/static` 文件到 `dist` 中
+
+教育子工程不会复制
+
+## 支持 typescript
+
+如果要开启 typescrit，只需要运行 `npx edu g ts`
+
+## 生成页面模版
+
+可以自动生成页面模版
+
+运行 `npx edu g page -h` 查看详细信息
+
+## 支持[自定义配置](override.md)
+
+运行 `npx edu g override` 生成控制文件
+
+## 自动根据 qsb 的 CDN 调整内部配置
+
+根据 `public/*.html` 文件里的 CDN 按需自动配置 externals 与 dll
+
+### CDN 匹配关键字
+
+`/react16.14.*_common31?.js/`
+
+- external: `react`, `react-dom`, `natty-fetch`, `natty-store`, `common-utils`
+- 添加内置的 dll 文件
+
+`/react16.14.*_axios0.21.1/`
+
+- external: `react`, `react-dom`, `natty-fetch`, `natty-store`, `common-utils`, `axios`
+
+`moment2.29.1.js`
+
+- external: `moment`
+
+`antd3.26.20.js`
+
+- external: `react`, `react-dom`, `moment`, `antd`
+
+如果使用 `antd3.26.20.js` 将额外执行下列规则
+
+`qsb-antd.min.js`
+
+- external: `@qsb/antd`, `@qse/antd`
+
+`qsb-scheme-render.min.js`
+
+- external: `@qsb/scheme-render` `@qse/scheme-render`
+
+## 支持 tailwindcss
+
+如果要开启 tailwindcss，只需要运行 `npx edu g tailwind`
+
+## PostCSS
+
+预处理很多样式[兼容性问题](https://preset-env.cssdb.org/features/#stage-2)
+
+为所有 `overflow: auto/scroll` 自动增加 `-webkit-overflow-scrolling: touch`
+
+为所有 `env(safe-area-inset-*)` 增加 fallback
+
+## Mock
+
+项目内建 mock 服务器，支持热更新，可以在 development 环境下使用
+
+mock 功能会根据 mock 文件夹自动判断是否开启
+
+可以通过 override.config.js 文件配置 mock 参数关闭该功能
+
+### 使用步骤
+
+根目录创建 mock 文件夹，在该文件夹下创建的所有 js、ts 文件都会被自动加载，可以创建多层级文件夹
+
+```js
+// path: /mock/index.js
+// path: /mock/depth/folder/index.js 支持深层文件
+
+import { defineMock } from '@qse/edu-scripts'
+
+export default defineMock({
+  'GET /api/test/test': { hello: 'world' },
+  'GET /api/test/test2': [1, 2, 3],
+  'POST /api/test2/test': (req, res) => {
+    console.log(req.body, req.cookies)
+    res.json({ foo: 'bar' })
+  },
+})
+```
+
+### mock 规则
+
+```ts
+import type { RequestHandler } from 'express'
+type Method = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'CONNECT' | 'TRACE'
+type API = string
+
+export type MockConfig = Record<
+  `${Method} ${API}`,
+  string | number | null | undefined | boolean | Record<string, any> | RequestHandler
+>
+
+export function defineMock(config: MockConfig) {
+  return config
+}
+```
+
+mock 名称是由 method 和 apiUrl 组成的，按这种规则去匹配
+
+所有 mock 文件最终会被合并到一起，形成一个大的对象。**所以当出现同名的 mock，前面的会被后面的覆盖**
+
+可以通过下面的方式去获取参数
+
+- `req.body` 获取 body 参数
+- `req.query` 获取链接上的参数
+- `req.cookies` 获取 cookies
+
+<Alert>mock 规则比 proxy 具有更高的优先级，如果匹配中了 mock，就会不再去 proxy 了</Alert>
+
+```ts
+// path: /mock/index.ts
+import Mock from 'mockjs'
+
+export default {
+  // method 必须是大写。可以直接返回数据
+  'GET /api/test': { hello: 'world' },
+
+  // 可以通过 express.requestHandler 处理请求。能实现自定义内容，发送文件等
+  'POST /api/test2': (req, res) => {
+    // 例如：将 body 内容返回
+    res.json(req.body)
+  },
+
+  // 可以通过第三方库生成 mock 数据
+  'POST /api/test3': Mock.mock({
+    // 属性 list 的值是一个数组，其中含有 1 到 10 个元素
+    'list|1-10': [
+      {
+        // 属性 id 是一个自增数，起始值为 1，每次增 1
+        'id|+1': 1,
+      },
+    ],
+  }),
+}
+```

package/docs/grayscale.md

@@ -0,0 +1,31 @@
+# 灰度测试
+
+## 开启灰度测试
+
+### PC 端
+
+前端只要在 `package.json` 文件中加入 `grayscale` 字段即可
+
+```json
+{
+  "name": "模块名称",
+  "edu": { "grayscale": true }
+}
+```
+
+此时打包出来的模块就成了灰度测试用的模块，会部署到指定的目录下，主工程会处理调度问题
+
+模块名称可与运维讨论
+
+后端接口会由 `nginx` 处理，前端不需要关注
+
+### H5 端
+
+h5 与 pc 是完全不同的方案，前端是需要将代码部署到两个地方。
+
+`/project-name` 与 `/beta_project-name`。第二个名字需要去问运维要
+
+#### 流程
+
+1. 访问 `/qsxxwapdev/project-name/index.html`
+2. 网关拦截 `index.html` 请求，并根据后台灰度配置进行分流，分别进入`/qsxxwapdev/project-name/index1.html` 与 `/qsxxwapdev/beta_project-name/index1.html`

package/docs/index.md

@@ -0,0 +1,15 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: '@qse/edu-scripts'
+  text: 教育工程化基础框架
+  actions:
+    - theme: brand
+      text: 快速开始
+      link: /install
+features:
+  - title: rspack重构
+    details: 使用rspack重构，比webpack快10x以上
+---

package/docs/install.md

@@ -0,0 +1 @@
+<!-- @include: ../README.md -->