Java 中 System.setProperty 用来在运行时设置系统属性（System Properties），这是 JVM 提供的一套全局键值配置。java -Dkey=value 命令行参数写的就是它。常见用途是设置编码、代理、日志实现、临时目录、SSL 协议等。本文说明它的作用范围、设置时机、安全限制与踩坑点。

一、它设置的是什么

系统属性存放在 System.getProperties() 返回的 Properties 对象里，JVM 启动时预置了一批（file.encoding、user.dir、java.io.tmpdir、os.name、java.version 等）。API 很简单：

System.setProperty("javax.net.ssl.trustStore", "/opt/certs/trust.p12");
String v = System.getProperty("java.io.tmpdir");
String v2 = System.getProperty("my.key", "默认值");   // 带默认值
Properties all = System.getProperties();
System.clearProperty("my.key");

二、时机决定成败：设置必须早于读取

这是最核心的坑。系统属性只是“配置”，库通常在初始化时读一次就缓存了，之后再改不生效。典型：

// 必须放在 main 最开始，且在用到该属性的类被加载之前
public static void main(String[] args) {
    System.setProperty("file.encoding", "UTF-8");   // 往往太晚了
    ...
}

• file.encoding：字符集在 JVM 启动时确定，运行时 setProperty 不会改变已加载类的行为，正确做法是启动参数 -Dfile.encoding=UTF-8 或（JDK18+）用 -Dstdout.encoding/-Dnative.encoding，JDK 18 起平台默认字符集已是 UTF-8。
• java.io.tmpdir：File.createTempFile 每次都会读，改动能生效。
• http.proxyHost/Port：影响 JVM 内置 URLConnection，需在建立连接前设置。
• log4j2.configurationFile、java.util.logging.config.file 等：日志框架初始化后改属性无效，必须早于首次取 Logger。

三、与命令行 -D、环境变量、配置文件的区别

常见混淆：Spring Boot 里 -Dspring.profiles.active=prod 与 --spring.profiles.active=prod（程序参数）都能用，但 System.setProperty 在 SpringApplication.run 之后设置就晚了。

四、线程安全与安全限制

• Properties 继承 Hashtable，方法本身是同步的，多线程写不会破坏结构；但“改了又读”的时序竞态依然存在——两个线程分别 setProperty 与库的初始化读取顺序不可控。实践建议：只在启动阶段设置，运行期不改。
• 启用 SecurityManager（JDK 17 起不推荐、后续版本移除）时，修改java.*、sun.* 前缀会抛 SecurityException。
• 不要把密钥、密码写进系统属性再打印到日志：System.getProperties() 常被诊断接口整体输出，会造成敏感信息泄露。Spring Boot Actuator 的 /env 端点尤其要注意鉴权。

五、实用示例

// 1) 让程序自带参数优先级更高，且不覆盖用户显式设置
if (System.getProperty("javax.net.ssl.trustStore") == null) {
    System.setProperty("javax.net.ssl.trustStore", "./cfg/trust.p12");
    System.setProperty("javax.net.ssl.trustStoreType", "PKCS12");
}

// 2) 读取自定义属性并给默认值
int pool = Integer.getInteger("my.pool.size", 8);   // 便捷方法
boolean dbg = Boolean.getBoolean("my.debug");        // 缺失即 false

// 3) 调试时打印全部属性（生产环境禁用）
if (Boolean.getBoolean("my.debug")) {
    System.getProperties().stringPropertyNames()
        .forEach(k -> System.out.println(k + "=" + System.getProperty(k)));
}

六、常见问题 FAQ

问：改了 file.encoding 中文仍乱码？
答：这是时机问题。改用启动参数；同时确认源文件本身的编码（IDE 设置）与输出端（终端代码页）。

问：setProperties 后能被其他 JVM 看到吗？
答：不能，系统属性只在当前进程内有效，不会写文件、不跨进程。

问：想给子进程传属性怎么办？
答：用 ProcessBuilder 启动时加 -Dkey=value 参数，子 JVM 才有。

要点：System.setProperty 写的是当前 JVM 进程内的一份全局键值表；能改不等于有效——大多数库只在初始化读一次，因此优先用 -D 启动参数、代码设置放最前面并加“未设置才设置”的判断；环境变量只读、属性不跨进程，且不要用它存密码或整体打印。

• Java
• JVM
• 系统属性