@ufly/sam v1.0.26

sam

 .--.    ,--.    _ .--..--.
( (`\]  `'_\ :  [ `.-. .-. |
 `'.'.  // | |,  | | | | | |
[\__) ) \'-;__/ [___||__||__]

@ufly/sam

提供 模拟多套域名环境（日常/预发/生产）能力，解决、CORS、登录态、https 等本地开发调试环境问题。定义为 simulator，取 same 之义，简名为 sam。

Support

无侵入的适配多开发框架

• midway-bin|mw
• max(umi4) / umi / dumi / nextjs
• taro / rax
• vite / webpack / vue-cli-service
• default
  • 基于koa、koa-static的peerDependencies 启动 Web Server 服务，便于预览项目编译构建后的效果

Usage

注： iOS手机安装证书后，需要信任手动安装的证书描述文件。

1. 安装依赖：yarn add @ufly/sam -D

2. 初始化 sam 配置文件 .samrc.js：在应用内根目录执行 $ npx sam init

   // .samrc.js
   const {
     env
   } = require('process');
   
   const https = env.HTTPS == 1;
   
   module.exports = {
     https,  // 是否启用https
     hosts: [  // 各环境域名
       'pre.my.domain.com',
       'daily.my.domain.com',
       'my.domain.com',
     ],
     // openUrl: 'https://www.baidu.com',  // 打开指定url
     path: 'app/index.html', // 应用入口
     // 数组形式，支持同时打开多页面
     // path: ['app/index.html', 'app/detail.html'],
   
     // 代理配置
     proxy: {
       // 开启代理日志，默认关闭
       silent: true,
       // 指定代理服务端口号，默认8880
       port: 8880,
       // 需要代理解析https的请求域
       rules: [
         'api.my.domain.com'
       ],
       // 配置忽略规则，对请求url匹配不做代理处置；支持数组、正则、字串三种方式
       ignore: ['dir/path', 'code/lib'], // /dir\/path/i、'dir/path'
     },
     // 配置构建结果目录，支持预览构建结果。配置 scripts { "preview": "sam dev"}
     webRoot: 'dist',
     silent: false, // 排查 dev 启动异常时打开，可查看详细log
     logLevel: 'DEBUG', // 排查 dev 启动异常时配置为 TRACE，可查看更详细log
   }

3. umi|dumi / vite / webpack / vue(vue-cli-service) / Rax / midway-bin|mw 等融合环境下配置。理论上，通过.samrc.js的cliPath配置，可与任何Cli本地服务融合。

• midway

  1. 配置dev服务启动脚本：package.json

     // 环境变更 HTTPS=1 NODE_ENV=local 与参数 --ts 按需选配
     {
       "scripts": {
         "dev": "cross-env HTTPS=1 NODE_ENV=local sam mw dev --ts",
       }
     }

• umi|dumi

  1. 配置 .umirc.js 或 config/config.dev.js：

     import { defineConfig } from 'umi';
     import { getCertPath } from '@ufly/sam';
     import { env } from 'process';
     
     const https = env.HTTPS == 1;
     const cert = getCertPath();
     
     export default defineConfig({
       //...,
       devServer: {
         https: https && cert
       }
     });

  2. 配置dev服务启动脚本：package.json

     {
       "scripts": {
         "dev": "cross-env REACT_APP_ENV=dev HTTPS=1 sam umi dev",
       }
     }

• vite

  1. vite 配置 vite.config.ts：

     // 以使用react为例
     import { defineConfig } from 'vite';
     import react from '@vitejs/plugin-react';
     import { getCertPath } from '@ufly/sam';
     import { env } from 'process';
     
     const https = env.HTTPS == 1;
     const cert = getCertPath();
     
     // https://vitejs.dev/config/
     export default defineConfig({
       server: {
         https: https && cert,
         hmr: {
           protocol: `ws${https?'s':''}`,
           host: 'localhost',
         }
       },
       plugins: [
         react(),
       ]
     })

  2. 配置dev服务启动脚本：package.json

     {
       "scripts": {
         "dev": "cross-env HTTPS=1 sam vite",
       }
     }

• webpack

  1. webpack 配置 webpack.config.js(基于webpack@^5举例，可结合webpack不同版本稍加调整)：

     const isProduction = process.env.NODE_ENV == 'production';
     
     // 仅列出 sam 相关，其他配置略
     const { getCertPath } = require('@ufly/sam');
     const { env } = require('process');
     const https = env.HTTPS == 1;
     const cert = getCertPath();
     
     const config = {
       // ...,
       devServer: {
         // 融合sam 配置
         allowedHosts: 'all',
         server: {
           type: `http${https ? 's' : ''}`,
           options: {
             ...cert,
           },
         },
         client: {
           webSocketURL: {
             protocol: `ws${https ? 's' : ''}`,
             hostname: 'localhost',
           },
         },
       },
       // ...
     };
     
     module.exports = () => {
       config.mode = isProduction ? 'production': 'development';
       return config;
     };

  2. 配置dev服务启动脚本：package.json

     {
       "scripts": {
         "dev": "cross-env HTTPS=1 sam webpack serve --stats-error-details",
       }
     }

• vue(vue-cli-service)

  1. vue 配置 vue.config.ts(基于webpack@^5举例，可结合webpack不同版本稍加调整)：

     const { defineConfig } = require('@vue/cli-service');
     const { getCertPath } = require('@ufly/sam');
     const { env } = require('process');
     
     const https = env.HTTPS == '1';
     const cert = getCertPath();
     
     module.exports = defineConfig({
       // 融合Sam 配置
       devServer: {
         allowedHosts: 'all',
         server: {
           type: `http${https ? 's' : ''}`,
           options: {
             ...cert,
           },
         },
         client: {
           webSocketURL: {
             protocol: `ws${https ? 's' : ''}`,
             hostname: 'localhost',
           },
         },
       }
     })

  2. 配置dev服务启动脚本：package.json

     {
       "scripts": {
         "dev": "cross-env HTTPS=1 sam vue serve",
         // 或者，二者都可
         "dev": "cross-env HTTPS=1 sam vue-cli-service serve",
       }
     }

• rax(通过插件定制工程)

  1. 在项目根目录下新建 build.plugin.js 文件

     const {
       getCertPath,
     } = require('@ufly/sam');
     const {
       env,
     } = require('process');
     
     const https = env.HTTPS == 1;
     const cert = getCertPath();
     
     module.exports = ({ context, onGetWebpackConfig }) => {
       onGetWebpackConfig((config) => {
         config.merge({
           // 融合Sam 配置
           devServer: {
             open: false,
             server: {
               type: `http${https ? 's' : ''}`,
               options: {
                 ...cert,
               },
             },
             webSocketServer: 'ws',
             client: {
               webSocketURL: {
                 protocol: `ws${https ? 's' : ''}`,
                 hostname: 'localhost',
               },
             },
           },
         });
       });
     };

  2. 在 build.json 里引入自定义插件：

     {
       "webpack5": true,
       "targets": [
         "web"
       ],
       "plugins": [
         "./build.plugin.js",  // 配置自定义插件
       ]
     }

  3. 配置dev服务启动脚本：package.json

     {
       "scripts": {
         "dev": "cross-env HTTPS=1 sam rax-app start"
       }
     }

• Taro 配置 config/dev.js

  const { getCertPath } = require('@ufly/sam');
  const { env } = require('process');
  
  const https = env.HTTPS == 1;
  const cert = getCertPath();
  
  module.exports = {
    env: {
      NODE_ENV: '"development"',
    },
    h5: {
      //..., 其他配置
      devServer: {
        open: false,
        https: https && cert,
        sockHost: 'localhost',
      },
    },
  };

preview

预览项目编译后的效果

1. 应用需要安装依赖：$ yarn add koa koa-static -D
2. 编辑 .samrc.js 配置，指定 webRoot 编译构建后的目录，如：webRoot: './dist'

3. 配置preview服务启动脚本：package.json

   {
     "scripts": {
       "preview": "cross-env HTTPS=1 sam dev"
     }
   }