@ufly/sam

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"
  }
}