cross-env 是一个 Node.js 包，专门用于解决不同操作系统间环境变量设置方式不一致的问题。它允许开发者在 Windows、Linux 和 macOS 上使用相同的命令来设置环境变量，极大地简化了跨平台开发的配置工作。
核心功能与工作原理
cross-env 的核心功能是通过统一接口在不同操作系统上执行相同的环境变量设置命令。它使用 Node.js 的 process.env 对象来设置环境变量，并确保这些设置在所有支持的操作系统上都能正确工作。
技术实现原理
-
平台检测：cross-env 首先检测当前运行的操作系统类型
-
命令转换：根据平台类型，将环境变量设置命令转换为适合当前系统的格式
-
在 POSIX 系统（Linux/macOS）上使用
export VAR=value语法 -
在 Windows 上使用
set VAR=value语法
-
-
子进程执行：通过 Node.js 的子进程模块执行转换后的命令
主要优势
-
跨平台兼容性：无缝支持 Windows、Linux 和 macOS
-
简化脚本编写：开发者无需为不同操作系统编写不同的环境变量设置脚本
-
提高可维护性：统一的脚本减少了维护成本和出错的可能性
-
轻量级：作为小型工具包，不会增加项目显著负担
安装与基本使用
安装方式
# 作为开发依赖安装（推荐）
npm install cross-env --save-dev
# 全局安装
npm install -g cross-env
基础用法示例
在 package.json 的 scripts 部分使用：
{
"scripts": {
"dev": "cross-env NODE_ENV=development node server.js",
"build": "cross-env NODE_ENV=production webpack --config webpack.config.js"
}
}
这样无论在哪类操作系统上运行 npm run dev 或 npm run build，NODE_ENV 都会被正确设置。
高级用法
设置多个环境变量
{
"scripts": {
"start": "cross-env NODE_ENV=production API_URL=https://api.example.com node app.js"
}
}
使用复杂表达式
{
"scripts": {
"test": "cross-env TS_NODE_COMPILER_OPTIONS='{\"module\":\"commonjs\"}' node test.js"
}
}
分离变量设置与命令执行
对于复杂的部署流程，可以采用"父-子脚本"方式：
{
"scripts": {
"prepareEnv": "cross-env API_KEY=12345 DB_HOST=localhost",
"start": "npm run prepareEnv && node app.js"
}
}
典型应用场景
-
构建工具配置：如 Webpack、Gulp 或 Grunt 中设置环境变量
-
测试框架：在运行测试前设置特定的环境变量
-
项目初始化：根据环境变量加载不同的配置文件
-
React/Vue 项目：区分开发和生产环境配置
-
多环境部署：为测试、预生产和生产环境使用不同配置
常见问题与解决方案
安装后脚本无法运行
可能原因：
-
cross-env 没有正确安装
-
package.json 中的脚本路径有误
解决方法：
-
确保 cross-env 已正确安装在 node_modules 目录下
-
检查 package.json 中的脚本路径
-
尝试重新安装依赖：
rm -rf node_modules npm install
跨平台行为不一致
可能原因：
-
使用了特定于某个操作系统的命令或语法
解决方法：
-
确保脚本中只使用 cross-env 设置环境变量
-
避免使用平台特定的命令（如 Linux 的
rm或 Windows 的del） -
在不同平台上进行充分测试
生态系统集成
cross-env 可以与大多数现代前端和Node.js工具链无缝集成：
-
Webpack：动态调整加载规则和插件
-
Jest：运行测试时管理环境变量
-
Vue CLI：区分开发和生产环境配置
-
React Scripts：创建React应用时设置环境变量
最佳实践
-
将cross-env作为开发依赖：因为它是构建工具而非运行时依赖
-
使用描述性变量名：如
API_BASE_URL而非简单的API_URL -
敏感信息处理：不要在环境变量中直接存储密码等敏感信息
-
文档化环境变量：在项目README中记录所有使用的环境变量及其用途
-
考虑使用.env文件：对于大量环境变量，可结合dotenv等包使用
总结
cross-env 是现代Node.js开发中不可或缺的工具之一，它解决了跨平台开发中环境变量设置的痛点，让开发者能够专注于业务逻辑而非平台差异。无论是小型项目还是大型企业级应用，cross-env 都能提供简单可靠的解决方案。
随着Node.js生态系统的不断发展，cross-env 因其简单性和可靠性而持续受到开发者社区的青睐，成为众多项目中的标准配置之一。
小试牛刀
多入口项目（Multi-entry Project）是指一个应用或系统有多个独立的入口点，每个入口点可以独立运行或组合使用。
1.创建多项目目录
在新建的项目下，创建$project文件，分别创建如下目录 ：
以下代码以app1为例：
App.vue:
<!-- App.vue -->
<template>
<Router-view />
</template>
<script setup lang="ts"></script>
router/index.js：
// index.ts
import { createRouter, createWebHashHistory } from "vue-router"
import { routes } from "./routes"
const router = createRouter({
history: createWebHashHistory(),
routes
})
export default router
router/routes.js：
// routes.ts
import type { RouteRecordRaw } from "vue-router";
export const routes: Array<RouteRecordRaw> = [
{
path: '/',
redirect: '/home'
},
{
path: '/home',
name: 'home',
component: () => import("../view/home/index.vue"),
}
]
view/home/index.vue
<!-- home/index.vue -->
<template>
app1 home
</template>
<script setup lang="ts"></script>
main.ts
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
createApp(App).use(router).mount('#app')
index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>app1</title>
</head>
<body>
<div id="app"></div>
<script type="module" src="./main.ts"></script>
</body>
</html>
2.配置子项目的env
.env.development
VITE_APP_BASE_URL=/stage-api
VITE_APP_PROJECT_NAME=app1
3.配置cross-env
安装cross-env:
pnpm i cross-env
在package.json中配置启动命令：
{
"name": "multi-entry-demo",
"private": true,
"version": "0.0.0",
"type": "module",
"scripts": {
"dev": "cross-env TARGET=app1 vite --host 0.0.0.0 ",
"dev:app1": "cross-env TARGET=app1 vite --host 0.0.0.0 ",
"dev:app2": "cross-env TARGET=app2 vite --host 0.0.0.0 ",
"build": "vue-tsc -b && vite build",
"preview": "vite preview"
},
"dependencies": {
"cross-env": "^7.0.3",
"html-webpack-plugin": "^5.6.3",
"vite-plugin-html": "^3.2.2",
"vue": "^3.5.13",
"vue-router": "^4.5.1"
},
"devDependencies": {
"@types/node": "^24.0.3",
"@vitejs/plugin-vue": "^5.2.3",
"@vue/tsconfig": "^0.7.0",
"typescript": "~5.8.3",
"vite": "^6.3.5",
"vue-tsc": "^2.2.8"
}
}
其中：设置环境变量 TARGET 为 app1/app2（用于区分不同入口）。
4.重要：配置多入口
在vite.config.ts中根据 TARGET 动态设置 root，添加：
root: TARGET ? resolve(__dirname, 'src', '$project', TARGET) : undefined,
5.运行
pnpm dev:app1
pnpm dev:app2
6.提升拓展
在每个子项目中配置入口html好像有点复杂，如果要统一配置所有子项目的标题，要进入每个子项目的html中进行 配置，所以这边采用的 办法是 在根目录的index.html中进行统一配置：
<!DOCTYPE html>
<html lang="zh">
<head>
<meta charset="UTF-8" />
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title><%= VITE_APP_PROJECT_NAME %></title>
</head>
<body>
<div id="app"></div>
<script type="module" src="<%= entry %>"></script>
</body>
</html>
其中，要想识别html中的模板，必须安装vite-plugin-html这插件
pnpm i vite-plugin-html
在vite.config.ts中引用并注入
import { createHtmlPlugin } from 'vite-plugin-html'
plugins: [
vue(),
createHtmlPlugin({
minify: true,
inject: {
data: {
title: env.VITE_APP_PROJECT_NAME,
entry: `/src/$project/${target}/main.ts`
}
}
}),
],
这样可以做到动态注入标题和js脚本，于是乎，每个子项目下的html文件就可以删掉啦。
7.打包
在package.json中加入以下代码：
"build": "vite build",
"build:app1": "pnpm type-check && cross-env TARGET=app1 pnpm build",
"build:app2": "pnpm type-check && cross-env TARGET=app2 pnpm build",
在vite.config.ts中加入以下代码：
build: {
sourcemap: !isPro,
// sourcemap: 'inline',
rollupOptions: {
input: {
// main: resolve(__dirname, 'index.html'),
main: resolve(__dirname, 'index.html')
},
output: {
// 为不同的入口配置不同的输出目录
dir: TARGET ? resolve(__dirname, `dist/${TARGET}`) : 'dist',
}
}
}
运行命令：
pnpm build:app2
扫一扫
1298
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
