Super Productivity 环境配置完全指南.env 动态变量与 TypeScript 静态环境的混合架构【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity本篇技术指南围绕 Super Productivity 仓库中 docs/ENV_SETUP.md 文档展开系统讲解该项目静态 TypeScript 环境文件 .env 动态变量的混合环境配置架构。你将掌握环境文件的分工与切换机制、load-env.js如何把.env生成类型安全的env.generated.ts常量、getEnv系列工具函数的使用方式以及完整的新增环境变量与安全实践流程可直接用于开发、构建与集成调试。一、环境配置的整体架构Super Productivity 采用混合式hybrid环境配置方案将两类信息分层管理静态基础配置以production、stage、version等标志为主写在静态 TypeScript 文件中随代码一起提交。动态与敏感配置以 API Key、访问令牌、WebDAV 账号等为主保存在.env文件中通过构建脚本转换为 TypeScript 常量不进入版本控制。这套方案的核心动机在于既有编译期可验证的静态标志又能让密钥类信息与源码隔离避免泄露。1.1 静态环境文件Static Environment Files仓库中存在三个静态环境文件文件用途productionstagesrc/environments/environment.ts开发环境配置falsefalsesrc/environments/environment.prod.ts生产环境配置truefalsesrc/environments/environment.stage.ts预发布/灰度环境配置truetrue三个文件的结构完全一致均从package.json中读取版本号例如开发环境文件的内容为// src/environments/environment.ts import pkg from ../../package.json; export const environment { production: false, stage: false, version: pkg.version, };从源码结构看version字段直接引用根目录 package.json 中的版本号保证应用版本与发布版本始终同步production/stage标志则决定了 Angular 在构建与运行时是否启用生产模式优化如 AOT、压缩、摇树等。Angular 的--configuration选项负责在production、stage、默认开发配置之间做文件替换。1.2 动态环境变量Dynamic Environment Variables.env存放面向所有环境的敏感/环境特定值例如第三方服务令牌默认不提交。src/app/config/env.generated.ts由脚本自动生成的 TypeScript 常量文件已被 gitignore。env.generated.ts的内容大致如下由脚本生成实际以生成结果为准// This file is auto-generated by tools/load-env.js // Do not modify directly - edit .env file instead export const ENV { DROPBOX_API_KEY: your-api-key-here, GOOGLE_DRIVE_TOKEN: your-token-here, } as const; export type EnvVars typeof ENV;二、环境搭建与接入步骤2.1 创建 .env 文件cp .env.example .env仓库根目录已提供 .env.example 模板其中给出了五个示例键均默认注释掉# GOOGLE_DRIVE_TOKENyour-token-here # DROPBOX_API_KEYyour-api-key-here # UNSPLASH_KEYyour-api-key-here # WEBDAV_URLhttps://your-webdav-server.com # WEBDAV_USERNAMEyour-username # WEBDAV_PASSWORDyour-password2.2 写入实际变量值# .env GOOGLE_DRIVE_TOKENyour-token-here DROPBOX_API_KEYyour-api-key-here UNSPLASH_KEYyour-unsplash-access-key WEBDAV_URLhttps://your-webdav-server.com WEBDAV_USERNAMEyour-username WEBDAV_PASSWORDyour-password这些变量分别服务于 Google Drive 备份同步、Dropbox 同步、Unsplash 背景图以及 WebDAV 同步后端等能力。需要注意.env中的值与OPTIONAL_ENV_KEYS列表见下文是取并集的关系脚本会把.env文件里的所有键一并纳入。2.3 在代码中访问环境变量生成的常量支持直接访问与工具函数两种方式// 方式一直接访问类型安全 import { ENV } from ./app/config/env.generated; const googleToken ENV.GOOGLE_DRIVE_TOKEN; // 方式二通过工具函数带类型安全 import { getEnv, getEnvOrDefault } from ./app/util/env; const googleToken getEnv(GOOGLE_DRIVE_TOKEN); const dropboxKey getEnvOrDefault(DROPBOX_API_KEY, default-key);三、运行与构建命令所有 npm 脚本都会在执行前自动调用load-env.js生成 TypeScript 常量# 开发模式默认环境 npm run startFrontend # 生产配置 npm run startFrontend:prod # 预发布配置 npm run startFrontend:stage对应构建命令同样会先完成常量生成# 生产构建 npm run buildFrontend:prod:es6 # 预发布构建 npm run buildFrontend:stage:es6需要特别说明的是所有命令共用同一个.env文件环境之间的差异完全由 Angular 的production/stage配置标志控制。从 package.json 可以看到脚本层面的配合env: node ./tools/load-env.js, serve: node ./tools/load-env.js --ensure ng serve, serveProd: node ./tools/load-env.js --ensure ng serve --configuration production--ensure参数对应 tools/load-env.js 中的占位模式当env.generated.ts尚不存在时自动生成一个空占位文件ENV {} as const从而保证即使没有.envng serve也能正常启动。四、底层工作原理4.1 load-env.js 的生成流程tools/load-env.js 是整个机制的枢纽其工作流程如下定义已知键内置REQUIRED_ENV_KEYS当前为空数组与OPTIONAL_ENV_KEYS两个白名单。OPTIONAL_ENV_KEYS包含 7 个已知可选项const OPTIONAL_ENV_KEYS [ UNSPLASH_KEY, UNSPLASH_CLIENT_ID, ONEDRIVE_CLIENT_ID, GOOGLE_DRIVE_TOKEN, DROPBOX_API_KEY, WEBDAV_URL, WEBDAV_USERNAME, WEBDAV_PASSWORD, ];合并变量来源先收集系统进程环境变量中命中白名单的键再通过dotenv.config({ path: .env })解析根目录.env文件用.env中的值覆盖同名键并把.env中出现的所有其他键一并并入环境对象。生成 TypeScript 内容对键名排序后生成export const ENV { ... } as const;与export type EnvVars typeof ENV;值中的反斜杠与单引号会被转义\→\\→\防止破坏字符串字面量。仅在有变化时写入对比现有文件内容若相同则输出up to date而不重复写入避免不必要的文件系统改动与重编译。透传后续命令若在--之后传入命令脚本会通过spawn以inherit模式透传执行便于把生成步骤与后续构建命令串成一条调用链。4.2 类型安全工具函数src/app/util/env.ts 提供了一组纯函数封装可在任意位置包括 Angular 上下文之外使用import { ENV } from ../config/env.generated; // 获取变量值未设置时返回 undefined export const getEnv (key: keyof typeof ENV): string | undefined { return ENV[key] || undefined; }; // 获取可选变量键名不在 REQUIRED_ENV_KEYS 中时也允许访问 export const getEnvOptional (key: string): string | undefined { return (ENV as any)[key] || undefined; }; // 获取数值型变量非法数值返回 undefined export const getEnvNumber (key: keyof typeof ENV): number | undefined { const value getEnv(key); if (value undefined) return undefined; const num Number(value); return isNaN(num) ? undefined : num; }; // 获取全部环境变量对象 export const getAllEnv (): typeof ENV ENV;其中getEnv的形参类型为keyof typeof ENV因此TypeScript 能感知全部可用键编写代码时自动补全、误拼键名会直接编译报错——这就是零process.env、全程类型安全的关键。仓库中已有实际调用示例例如 src/app/core/unsplash/unsplash.service.ts 第 48 行private readonly ACCESS_KEY getEnvOptional(UNSPLASH_KEY);而 src/app/imex/sync/onedrive-auth-mode.const.ts 同样通过getEnvOptional读取 OneDrive 相关客户端配置印证了该机制在第三方服务集成中的真实使用。五、安全注意事项绝不提交.env密钥一旦入库即视为泄露。仓库 .gitignore 已同时忽略.env、.env.*与src/app/config/env.generated.ts。生成文件同样不入库env.generated.ts由脚本生成、被 gitignore任何协作者都要在本地cp .env.example .env后重新生成。编译期注入而非运行时暴露密钥在构建时被编译进 bundle不会以环境变量形式暴露在运行时进程环境中。.env.example只放非敏感示例值模板中的令牌均为占位符用于说明键名与格式。六、新增环境变量的完整流程在.env中添加新键NEW_API_KEYyour-api-key-here运行任意构建/启动命令或直接执行npm run env脚本会自动把它并入ENV类型定义随之更新。以全类型安全方式使用import { ENV } from ./app/config/env.generated; const apiKey ENV.NEW_API_KEY; // 或使用工具函数 import { getEnv } from ./app/util/env; const apiKey getEnv(NEW_API_KEY); // TypeScript 知道所有可用键补充建议若新变量属于可选集成能力如某个插件或第三方服务开关可将其加入load-env.js的OPTIONAL_ENV_KEYS白名单便于脚本在启动日志中提示检测到/未检测到该变量若属于缺了就无法运行的关键项则应放入REQUIRED_ENV_KEYS脚本在缺失时会直接抛错中断把配置错误暴露在构建阶段而非运行时。七、该方案的核心收益类型安全完整 TypeScript 支持与自动补全键名错误在编译期即被拦截。零运行时依赖常量在构建期被编译进 bundle运行时不需要process.env或额外的 webpack 配置。跨平台通用浏览器、Electron 容器、PWA 等环境均直接 import 使用。简单直观复制模板、填入变量、import 使用三步即完成接入。安全隔离敏感信息只存在于.env绝不进入版本控制生成文件亦被 gitignore。该方案在开发期、CI 与发布流水线中均可复用本地开发直接使用.envCI 通过注入系统环境变量 .env覆盖机制可灵活配置集成测试所需令牌生产与预发布构建则依靠environment.prod.ts/environment.stage.ts的静态标志完成行为差异控制最终形成一套静态标志管行为、动态变量管密钥的清晰职责边界。【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考