diff --git a/shared/utils/logger.ts b/shared/utils/logger.ts
new file mode 100644
index 0000000..c77d169
--- /dev/null
+++ b/shared/utils/logger.ts
@@ -0,0 +1,110 @@
+/**
+ * 日志等级枚举
+ *
+ * - `debug`  : 开发调试日志（最低）
+ * - `info`   : 普通信息输出
+ * - `warn`   : 警告信息
+ * - `error`  : 错误信息（最高级别）
+ * - `silent` : 屏蔽所有日志
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+
+/**
+ * 每个日志级别的优先级数值
+ * 数值越小，级别越低
+ */
+const levelPriority: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4,
+};
+
+/**
+ * 检测当前运行环境应使用的日志等级：
+ *
+ * - 开发环境：默认 `debug`
+ * - 生产环境：默认 `warn`
+ * - 浏览器允许通过 `localStorage.DEBUG = 'true'` 强制开启 `debug`
+ */
+function detectInitialLevel(): LogLevel {
+  const isProduction = process.env.NODE_ENV === 'production';
+  if (import.meta.client && localStorage.getItem('DEBUG') === 'true') {
+    return 'debug';
+  }
+
+  return isProduction ? 'warn' : 'debug';
+}
+
+/**
+ * 核心日志类
+ *
+ * 提供 `debug / info / warn / error` 四个级别
+ * 并支持通过 `setLevel` 动态调整输出等级
+ *
+ * @example
+ * ```ts
+ * logger.debug('User data:', user)
+ * logger.error(new Error('Something broke'))
+ * logger.setLevel('silent')
+ * ```
+ */
+class Logger {
+  /** 当前日志等级（默认由 detectInitialLevel 判断） */
+  private level: LogLevel = detectInitialLevel();
+
+  /**
+   * 手动设置日志输出级别
+   *
+   * @param level 目标日志级别
+   *
+   * @example
+   * ```ts
+   * logger.setLevel('silent') // 全部禁用
+   * logger.setLevel('debug')  // 强制打印全部日志
+   * ```
+   */
+  setLevel(newLevel: LogLevel) {
+    this.level = newLevel;
+  }
+
+  /**
+   * 判断当前等级是否允许输出指定日志
+   */
+  private canLog(level: LogLevel): boolean {
+    return levelPriority[level] >= levelPriority[this.level];
+  }
+
+  /** 输出调试日志（开发阶段使用） */
+  debug(...args: unknown[]) {
+    if (this.canLog('debug')) console.debug('[DEBUG]', ...args);
+  }
+
+  /** 输出普通信息日志 */
+  info(...args: unknown[]) {
+    if (this.canLog('info')) console.info('[INFO]', ...args);
+  }
+
+  /** 输出警告日志 */
+  warn(...args: unknown[]) {
+    if (this.canLog('warn')) console.warn('[WARN]', ...args);
+  }
+
+  /** 输出错误日志 */
+  error(...args: unknown[]) {
+    if (this.canLog('error')) console.error('[ERROR]', ...args);
+  }
+}
+
+/**
+ * 默认导出的单例 logger
+ *
+ * @example
+ * ```ts
+ * import { logger } from '~/utils/logger'
+ *
+ * logger.info('App started')
+ * ```
+ */
+export const logger = new Logger();